> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Job Status

> Get the status and progress of an import or account research job

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.

```bash cURL theme={null}
curl "https://api.clustr-ai.com/api/public/jobs/job_jctzmfh41nr4v8hvs87eakgs48" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json 200 theme={null}
{
  "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"
  }
}
```

```json 200 (failed) theme={null}
{
  "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"
  }
}
```

```json 404 theme={null}
{
  "success": false,
  "error": { "message": "Job not found", "code": "NOT_FOUND" }
}
```


## OpenAPI

````yaml GET /jobs/{id}
openapi: 3.1.0
info:
  title: Clustr Public API
  description: >
    Programmatic access to your Clustr network: import connectors, search warm
    intros (opportunities), and manage target accounts.


    ## Authentication

    All endpoints require a Bearer token (API key) in the `Authorization`
    header.


    ```

    Authorization: Bearer <your_api_key>

    ```


    API keys can be created and managed from the [API settings
    page](https://app.clustr-ai.com/api).
  version: '1.0'
  contact:
    name: Clustr Support
    url: https://clustr-ai.com
servers:
  - url: https://api.clustr-ai.com/api/public
    description: Production
security:
  - BearerAuth: []
paths:
  /jobs/{id}:
    get:
      tags:
        - Jobs
      summary: Get Job Status
      description: Get the status and progress of an import job.
      operationId: getJobStatus
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >-
            The job's Clustr ID (`job_…`), from [List
            Jobs](/api-reference/list-jobs) or the import that

            started it. The id from earlier responses also works.
          example: job_9hn4bhkchhfqzfvsmz3pyn9r9f
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/JobPublicResponse'
        '401':
          description: Invalid or missing API key
        '404':
          description: Job not found
components:
  schemas:
    JobPublicResponse:
      type: object
      description: An import job and its progress.
      required:
        - job_id
        - status
        - progress
        - created_at
      properties:
        clustr_job_id:
          type: string
          description: >-
            The job's Clustr ID, for example `job_jctzmfh41nr4v8hvs87eakgs48`.
            Follow the job with [Get Job

            Status](/api-reference/get-job-status).
          example: job_jctzmfh41nr4v8hvs87eakgs48
        job_id:
          type: string
          example: 87de0cc4-f258-4090-ab79-3f278bd7578e
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustr_job_id`.
        status:
          type: string
          description: >-
            The job's status. `QUEUED` means the job was accepted and charged
            and is waiting to start: when your workspace already has imports in
            progress, a new job may be queued, and it starts automatically once
            capacity frees up.
          enum:
            - QUEUED
            - PROCESSING
            - COMPLETED
            - FAILED
            - CANCELLED
          example: COMPLETED
        progress:
          type: object
          properties:
            current_stage:
              type: string
            stages:
              type: object
        error_messages:
          type: array
          description: >-
            The raw messages the job recorded, useful when you contact support.
            To show your users why a job failed, use `failure_reason`.
          items:
            type: string
        failure_reason:
          type: string
          description: >-
            Present on a `FAILED` job: why it failed, as a plain-English
            sentence that says what to do next.
          example: >-
            Company not found on LinkedIn. Check the link points to the
            company's own page and retry.
        reason_code:
          type: string
          description: >-
            Present on a `FAILED` job: the stable code behind `failure_reason`.
            One of `company_not_found`, `excluded_company`, `no_target_titles`,
            `insufficient_credits`, `linkedin_disconnected`, `no_results`,
            `report_failed`, `timed_out`, `internal_error`, `other` or
            `unknown`. New codes may be added.
          example: company_not_found
        overlaps_pending:
          type: boolean
          description: >-
            True when the job has finished but some of its connector and
            prospect pairs are still being computed, so the number of
            opportunities it produced can still grow. False once they are done,
            and while the job is still running. Omitted when this state is
            unavailable.
          example: false
        derive_incomplete:
          type: boolean
          description: >-
            Present on a `COMPLETED` import whose warm intros were still being
            computed when the run ended, after two hours without progress or at
            the job time limit. The import is usable, and the remaining people
            finish in the background. Omitted otherwise.
          example: true
        derive_incomplete_reason:
          type: string
          enum:
            - stalled
            - backstop
          description: >-
            Why `derive_incomplete` is set: `stalled` (no progress for two
            hours) or `backstop` (the job time limit). Present only with
            `derive_incomplete`. New values may be added.
          example: stalled
        derive_note:
          type: string
          description: >-
            Present only with `derive_incomplete`: a plain-English sentence to
            show next to the status.
          example: >-
            Completed, but some intros are still being calculated. They will
            appear within the next hours without any action from you.
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: The API key you created on the API settings page of the Clustr app.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.