Get Job Status

GET

jobs

{id}

curl "https://api.clustr-ai.com/api/public/jobs/job_jctzmfh41nr4v8hvs87eakgs48" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "clustr_job_id": "job_jctzmfh41nr4v8hvs87eakgs48",
    "job_id": "job_abc123",
    "status": "PROCESSING",
    "progress": {
      "current_stage": "extracting_prospects",
      "stages": {
        "ingesting_contacts": { "contacts_fetched": 5, "contacts_total": 5 },
        "extracting_prospects": { "prospects_found": 120 },
        "enriching_prospects": { "prospects_enriched": 0 },
        "processing_companies": { "companies_enriched": 0 },
        "creating_relationships": { "relationships_created": 0 }
      }
    },
    "created_at": "2025-03-15T10:00:00Z"
  }
}

{
  "success": true,
  "data": {
    "clustr_job_id": "job_nxe4yazb0yvcwdfwdhj2ycqnjd",
    "job_id": "e0cc3d83-7e6a-4e99-a596-84ad8476ea80",
    "status": "FAILED",
    "failure_reason": "Company not found on LinkedIn. Check the link points to the company's own page and retry.",
    "reason_code": "company_not_found",
    "error_messages": [
      "Target company could not be found on LinkedIn for URL \"https://www.linkedin.com/company/bneu\". Check that the link points to the company's own LinkedIn page (not a sub-brand, regional sub-page, or search result) and retry."
    ],
    "created_at": "2026-09-29T12:36:48Z",
    "completed_at": "2026-09-29T13:42:43Z"
  }
}

{
  "success": false,
  "error": { "message": "Job not found", "code": "NOT_FOUND" }
}

Get detailed status and progress for a specific import or account research job. status is one of QUEUED, PROCESSING, COMPLETED, FAILED, CANCELLED. A job is QUEUED when it has been accepted and charged but has not started yet, typically because your workspace already had imports in progress. It starts automatically, oldest first, once capacity frees up, so no action is needed; keep polling this endpoint until it moves to PROCESSING.

When a job fails

A FAILED job carries two more fields:

failure_reason: why it failed, as a sentence that says what to do next. Show this to your user.
reason_code: the same as a stable code, for your code to branch on.

`reason_code`	What happened
`company_not_found`	The LinkedIn URL did not lead to a company page. Use the company’s own page, not a sub-brand, a regional page or a search result
`excluded_company`	The company is on your workspace’s excluded list
`no_target_titles`	Your workspace has no target job titles set
`insufficient_credits`	Not enough credits to run it
`linkedin_disconnected`	The LinkedIn connection it needed has expired
`no_results`	It finished without finding anyone to report on
`report_failed`	The report could not be built
`timed_out`	It took too long and was stopped
`internal_error`	Something went wrong on our side
`other`	None of the above; `failure_reason` is the message the run recorded
`unknown`	It stopped without recording why

New codes may be added. error_messages keeps the raw text for support.

When a finished job is still settling

overlaps_pending is true when the job has finished (COMPLETED, FAILED or CANCELLED) but some of its warm-intro overlaps are still being worked out in the background. The job’s opportunity count can still grow until it turns false, so wait and read again before you treat the numbers as final. It is false once nothing is left, and always false while the job is still PROCESSING or QUEUED: check status first. If it is missing, the lookup could not be made; read again.

When an import finishes with derivation incomplete

A COMPLETED import carries derive_incomplete: true when the warm-intro derivation did not finish inside the run. derive_incomplete_reason says why: stalled (no progress for two hours) or backstop (the job time limit). derive_note is a plain-English sentence to show next to the status. The import is usable; the remaining intros are calculated in the background and appear over the next hours, with nothing to do. The three fields are absent on every other job. New reasons may be added.

curl "https://api.clustr-ai.com/api/public/jobs/job_jctzmfh41nr4v8hvs87eakgs48" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "clustr_job_id": "job_jctzmfh41nr4v8hvs87eakgs48",
    "job_id": "job_abc123",
    "status": "PROCESSING",
    "progress": {
      "current_stage": "extracting_prospects",
      "stages": {
        "ingesting_contacts": { "contacts_fetched": 5, "contacts_total": 5 },
        "extracting_prospects": { "prospects_found": 120 },
        "enriching_prospects": { "prospects_enriched": 0 },
        "processing_companies": { "companies_enriched": 0 },
        "creating_relationships": { "relationships_created": 0 }
      }
    },
    "created_at": "2025-03-15T10:00:00Z"
  }
}

{
  "success": true,
  "data": {
    "clustr_job_id": "job_nxe4yazb0yvcwdfwdhj2ycqnjd",
    "job_id": "e0cc3d83-7e6a-4e99-a596-84ad8476ea80",
    "status": "FAILED",
    "failure_reason": "Company not found on LinkedIn. Check the link points to the company's own page and retry.",
    "reason_code": "company_not_found",
    "error_messages": [
      "Target company could not be found on LinkedIn for URL \"https://www.linkedin.com/company/bneu\". Check that the link points to the company's own LinkedIn page (not a sub-brand, regional sub-page, or search result) and retry."
    ],
    "created_at": "2026-09-29T12:36:48Z",
    "completed_at": "2026-09-29T13:42:43Z"
  }
}

{
  "success": false,
  "error": { "message": "Job not found", "code": "NOT_FOUND" }
}

Authorizations

Authorization

string

header

required

The API key you created on the API settings page of the Clustr app.

Path Parameters

string

required

The job's Clustr ID (job_…), from List Jobs or the import that started it. The id from earlier responses also works.

Response

Job details

success

boolean

required

data

object

required

An import job and its progress.

Show child attributes

curl "https://api.clustr-ai.com/api/public/jobs/job_jctzmfh41nr4v8hvs87eakgs48" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "clustr_job_id": "job_jctzmfh41nr4v8hvs87eakgs48",
    "job_id": "job_abc123",
    "status": "PROCESSING",
    "progress": {
      "current_stage": "extracting_prospects",
      "stages": {
        "ingesting_contacts": { "contacts_fetched": 5, "contacts_total": 5 },
        "extracting_prospects": { "prospects_found": 120 },
        "enriching_prospects": { "prospects_enriched": 0 },
        "processing_companies": { "companies_enriched": 0 },
        "creating_relationships": { "relationships_created": 0 }
      }
    },
    "created_at": "2025-03-15T10:00:00Z"
  }
}

{
  "success": true,
  "data": {
    "clustr_job_id": "job_nxe4yazb0yvcwdfwdhj2ycqnjd",
    "job_id": "e0cc3d83-7e6a-4e99-a596-84ad8476ea80",
    "status": "FAILED",
    "failure_reason": "Company not found on LinkedIn. Check the link points to the company's own page and retry.",
    "reason_code": "company_not_found",
    "error_messages": [
      "Target company could not be found on LinkedIn for URL \"https://www.linkedin.com/company/bneu\". Check that the link points to the company's own LinkedIn page (not a sub-brand, regional sub-page, or search result) and retry."
    ],
    "created_at": "2026-09-29T12:36:48Z",
    "completed_at": "2026-09-29T13:42:43Z"
  }
}

{
  "success": false,
  "error": { "message": "Job not found", "code": "NOT_FOUND" }
}

API Reference

Import

Search

Jobs

Network

Opportunities

Owners

Accounts

Account States

Saved Views

Workflows

Intro Requests

Notes

Record Activity

Tags

Target Accounts

Client Companies

Excluded Companies

Buyer Titles

ICP

Competitor Monitoring

Connector Refresh

Notifications

Get Job Status

When a job fails

When a finished job is still settling

When an import finishes with derivation incomplete

Authorizations

Path Parameters

Response

​When a job fails

​When a finished job is still settling

​When an import finishes with derivation incomplete

Authorizations

Path Parameters

Response

When a job fails

When a finished job is still settling

When an import finishes with derivation incomplete