---

name: clari-hello-world description: >- Run one bounded Clari forecast export through request, status polling, and result retrieval. Use when proving Revenue API connectivity or learning the job lifecycle. Trigger with: "run my first Clari export", "test Clari connectivity", "export a forecast snapshot". allowed-tools: Read, Grep, Write, Edit version: 2.0.0 argument-hint: '[forecast-id-time-period-and-output-format]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• clari
• forecast
• export
• quickstart compatibility: 'Requires a Revenue API token, access to an existing Forecast Tab, and permission to export its hierarchy.'

---

First Clari Forecast Export

Overview

Prove the complete asynchronous export contract with one small, non-production forecast request. Success means retaining the forecast ID, job ID, terminal state, result format, and a redacted schema sample—not merely receiving an initial HTTP response.

Prerequisites

• Forecast Tab ID copied from the entitled Clari Forecast view
• A scoped Revenue API token stored outside the repository
• A small time period, hierarchy scope, and approved output location

Instructions

Step 1: Freeze the request

Record the forecast ID, time period, requested data types, scope ID, currency, history choice, and JSON or CSV format.

Step 2: Check capacity

Read /admin/limits and confirm both concurrent capacity and rolling monthly quota before consuming an export slot.

Step 3: Queue the export

Submit POST /export/forecast/{forecastId} against the documented Revenue API base and retain the returned job ID.

Step 4: Poll deliberately

Read /export/jobs/{jobId} with bounded backoff until DONE, ABORTED, or an operator-defined timeout. Do not treat SCHEDULED or STARTED as completion.

Step 5: Retrieve once

Only after DONE, fetch /export/jobs/{jobId}/results, validate content type and shape, and store the result in the approved temporary boundary.

Step 6: Close the proof

Record row count, schema fingerprint, status timeline, and cleanup result; delete temporary exported data according to policy.

Authentication

Use the Revenue API token only in the apikey header over HTTPS. Never include the header, raw response body, or revenue values in logs; authorization follows the token owner’s Clari access and hierarchy.

Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

Output

• Redacted request manifest and returned job ID
• Terminal-state timeline and result schema fingerprint
• Pass/fail decision with cleanup receipt

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

Examples

An operator requests a JSON export for one current-quarter Forecast Tab, observes SCHEDULED, STARTED, and DONE, retrieves the result once, and records field names and row count without retaining deal values in the test artifact.

Error Handling

Failure	Response
Forecast ID rejected	Re-copy the ID from the intended Forecast Tab and verify the integration identity is opted into that hierarchy.
Job remains non-terminal	Stop at the timeout, retain the job ID, inspect service status, and avoid queuing duplicate jobs.
Results request fails	Confirm the job is DONE, the job ID belongs to the same token, and the export has not expired.

Resources

• First-party source notes
• Clari Revenue API reference
• Clari service status