Clari Hello World Skill

Clari Hello World

Overview

First API calls against Clari: list available forecasts, export a forecast snapshot, and check export job status. The Clari Export API is the primary integration point for getting forecast, quota, and CRM data out of Clari.

Prerequisites

Completed clari-install-auth setup
CLARI_API_KEY environment variable set
At least one forecast configured in Clari

Instructions

Step 1: List Available Forecasts

curl -s -H "apikey: ${CLARI_API_KEY}" \
  https://api.clari.com/v4/export/forecast/list \
  | jq '.forecasts[] | {forecastName, forecastId, timePeriods}'

Step 2: Export a Forecast

import requests
import json
import os
import time

api_key = os.environ["CLARI_API_KEY"]
headers = {"apikey": api_key, "Content-Type": "text/plain"}

# Replace with your forecast name from Step 1
forecast_name = "company_forecast"

payload = json.dumps({
    "timePeriod": "2026_Q1",
    "typesToExport": [
        "forecast",
        "quota",
        "forecast_updated",
        "adjustment",
        "crm_total",
        "crm_closed"
    ],
    "currency": "USD",
    "schedule": "NONE",
    "includeHistorical": False,
    "exportFormat": "JSON"
})

response = requests.post(
    f"https://api.clari.com/v4/export/forecast/{forecast_name}",
    headers=headers,
    data=payload,
)
response.raise_for_status()

job = response.json()
print(f"Export job started: {job['jobId']}")
print(f"Status: {job['status']}")

Step 3: Check Export Job Status

# Poll for job completion
job_id = job["jobId"]

while True:
    status_resp = requests.get(
        f"https://api.clari.com/v4/export/jobs/{job_id}",
        headers={"apikey": api_key},
    )
    status = status_resp.json()

    if status["status"] == "COMPLETED":
        print(f"Export ready: {status['downloadUrl']}")
        break
    elif status["status"] == "FAILED":
        print(f"Export failed: {status.get('error', 'Unknown')}")
        break

    print(f"Status: {status['status']}... waiting 5s")
    time.sleep(5)

Step 4: Download and Parse Results

if status["status"] == "COMPLETED":
    download = requests.get(status["downloadUrl"])
    forecast_data = download.json()

    # Print summary
    for entry in forecast_data.get("entries", [])[:5]:
        print(f"  Rep: {entry.get('ownerName')}")
        print(f"  Forecast: ${entry.get('forecastAmount', 0):,.0f}")
        print(f"  Quota: ${entry.get('quotaAmount', 0):,.0f}")
        print()

Output

List of forecasts with IDs and time periods
Exported forecast data with rep-level calls
Quota, adjustments, and CRM totals

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | 401 Unauthorized | Bad API key | Regenerate token in Clari settings | | No forecasts listed | Wrong org or no forecasts configured | Contact Clari admin | | Job stays PENDING | Large export | Wait longer, check job status endpoint | | 404 on forecast name | Name mismatch | Use exact name from list endpoint |

Resources

Next Steps

Proceed to clari-local-dev-loop for development workflow setup.

Agent Skills: Clari Hello World

Install this agent skill to your local

Skill Files