Polling & Async Results

Several API v2 operations run in the background. This page explains how to get their results.

Which operations are async?

Synchronous operations (company enrichment, by-task for companies and the JSON export) return their results directly and need no polling. CRM and sequencer sync of up to 500 leads also returns final counts in the response; check status, because a bigger list comes back pending. A CSV export waits up to 20 seconds for the file; if it isn’t ready you get HTTP 202, and each call with the job_id waits up to 20 seconds again.

Polling enrichment status

GET /enrichment/status/{workflow_id}

Scope: enrich:read · Cost: free

Poll until status is terminal: completed, completed_with_errors or failed. A run that was stopped ends cancelled, canceled or terminated. A bulk run with any failed rows settles as completed_with_errors, not completed, so a loop that only checks for completed never exits; always treat completed_with_errors as terminal. The non-terminal states are pending and processing. The handle can be a workflow_id (enrich-..., bulk-enrich-...) or a cl-task_... cohort handle.

import time, requests
 
H = {"Authorization": "Bearer clapi_your_api_key"}
B = "https://api.cleanlist.ai/api/v2"
TERMINAL = ("completed", "completed_with_errors", "failed", "cancelled", "canceled", "terminated")
 
def wait_for(workflow_id, interval=5, timeout=900):
    deadline = time.time() + timeout
    while time.time() < deadline:
        s = requests.get(f"{B}/enrichment/status/{workflow_id}", headers=H).json()
        if s["status"] in TERMINAL:
            return s
        time.sleep(interval)
    raise TimeoutError(workflow_id)

const B = "https://api.cleanlist.ai/api/v2";
const H = { Authorization: "Bearer clapi_your_api_key" };
const TERMINAL = ["completed", "completed_with_errors", "failed", "cancelled", "canceled", "terminated"];
 
async function waitFor(workflowId, interval = 5000, timeout = 900000) {
  const deadline = Date.now() + timeout;
  while (Date.now() < deadline) {
    const s = await (await fetch(`${B}/enrichment/status/${workflowId}`, { headers: H })).json();
    if (TERMINAL.includes(s.status)) return s;
    await new Promise((r) => setTimeout(r, interval));
  }
  throw new Error(`timeout: ${workflowId}`);
}

See Enrichment: Status for the full response, including the inline result for single-person runs and the settled credits_charged and credits_refunded.

Polling tips

• Free, but within rate limits. Status polls cost no credits but count toward the 60 requests per minute per organization (and 30 per key). Poll every few seconds; back off for long bulk jobs.
• Read the counters. total, processed, completed and failed show live progress on bulk runs.
• Watch refund_status. A terminal failure on a prepaid run sets refund_status: "pending_review" with a message to contact support; show it to the user.
• Bulk results aren’t inline. For bulk and cohort runs, read the enriched leads from the target list with GET /lead-lists/{id}/leads once the workflow completes.
• Smart-agent results grow. GET /smart-agents/{id} returns the per-lead results that are finished so far, so a running job returns a partial set.

Chaining with task_id

Many responses carry a task_id in the envelope, a short-lived cohort handle. It’s the glue for multi-step workflows:

1. Search: POST /people/find returns rows and a task_id for the result cohort.
2. Save or enrich the cohort: pass that task_id to POST /lead-lists/{id}/leads (free), or to POST /enrichment/by-task with a quote. By-task returns a workflow_id.
3. Poll: poll the workflow_id (or the cl-task_... handle) with GET /enrichment/status until terminal.

The same works for GET /lead-lists/{id}/leads, which returns a task_id for the page so you can enrich a page of an existing list the same way.

Learn more

• Enrichment endpoints
• Smart agents
• Lead lists
• Credits & the quote model
• Errors & rate limits