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, CRM and sequencer sync and exports) return their results directly and need no polling. Sync responses include a workflow_id for consistency, but the counts are already final.

Polling enrichment status

GET /enrichment/status/{workflow_id}

Scope: enrich:read · Cost: free

Poll until status is terminal: completed, completed_with_errors or failed. Single-record runs can also end 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", "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", "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