---
title: "Get Company Enrichment Job Status"
method: GET
path: "/v1/companies/enrichment-jobs/{job_id}"
tags: ["Companies", "Enrichment", "v1"]
---

# Get Company Enrichment Job Status

`GET /v1/companies/enrichment-jobs/{job_id}`

## Request

- Base URL: `https://api.leadfeeder.com`
- URL: `https://api.leadfeeder.com/v1/companies/enrichment-jobs/{job_id}`
- Auth: one of:
  - API key in header `X-Api-Key`
  - OAuth 2
    - Authorization code: `https://api.leadfeeder.com/v1/oauth/authorize`
    - Token URL: `https://api.leadfeeder.com/v1/oauth/token` scopes: `companies:read`

Retrieve the current status of a Company AI Enrichment job, with any errors. `credits.estimated` is set when the job is created if it targets `company_ids`, and otherwise once the job has found the companies to enrich. `credits.consumed` is reported once the job has finished. The counts in `summary` can appear shortly before `status` changes.
Jobs are kept for 7 days after creation. A job that stops unexpectedly can stay `running` until then.
Credit Note: This endpoint does not consume credits.

:::info
Requires the `companies:read` OAuth2 scope.
:::

## Path parameters

- `job_id` string, required

## Query parameters

- `account_id` string, required

## Response `200`

Job status retrieved

- object
  - `data` EnrichmentJobV1, required
    - `attributes` object, required
      - `completed_at` string, date-time, nullable: When the job finished. Present only once the job has reached `completed` or `failed`.
      - `configuration` object: The settings the job was created with: `custom_field_id`, `enrichment_strategy`, `company_ids`, `list_id` and `advanced_search`, each when it was sent. The response that creates the job has no `configuration`.
        - `advanced_search` object: A set of companies selected by an advanced search query, instead of an explicit `company_ids` list. The companies matching `filters` are taken in `sort` order, limited to `page.size`, with any `excluded_company_ids` removed.
          - `excluded_company_ids` string[]: Company IDs to remove from the matched set (for example, rows the user deselected). Removed after the `page.size` limit is applied, so the final selection may be smaller than `page.size`.
          - `filters` object, required: Recursive filter tree applied to the company population. The root is always a `group` whose `items` are either individual filters or further `group` nodes (combined with `and`/`or`). The tree holds at most 50 filters and groups, the root included, and at most 5 levels of groups.
            - `items` CompaniesAdvancedSearchFilterItem[], required: Nested filter conditions or sub-groups. Each item is either a `filter` or a nested `group`. An empty list matches every company.
              - …
            - `operator` 'and' | 'or', required: The logical operator combining the items.
            - `type` 'group', required: Indicates this is the root filter group.
          - `page` object: Bounds how many of the matching companies are selected.
            - `size` integer: Maximum number of matching companies to select, taken in `sort` order. Omit to select every match, up to the endpoint's per-job maximum.
          - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering.
            - `direction` 'asc' | 'desc': Sort direction. Defaults to `asc`.
            - `field` string: Comma-separated list of company attributes to sort by, applied in order (e.g. `employee_count,name`). Allowed values: `relevance`, `name`, `employee_count`, `revenue`, `founded_year`. Unknown values are rejected with `invalid_parameter`.
        - `company_ids` string[]: Specific company IDs targeted (mutually exclusive with list_id)
        - `custom_field_id` string: The custom field being enriched
        - `enrichment_strategy` 'missing_values' | 'all' | 'preview': Which records to enrich
        - `list_id` string: The `list_id` the job was created with.
      - `created_at` string, date-time, required: When the job was created
      - `credits` object: Credit consumption details
        - `consumed` number: Credits consumed so far. Some job types are priced per record at a fractional rate, so this can be a decimal.
        - `estimated` number: Credits estimated for the job. Some job types are priced per record at a fractional rate, so this can be a decimal.
      - `errors` object[]: Present only when status is `failed`. When a job created from a search selection fails because the search rejected its filters or sort, or failed itself, it holds the search's own code and title, such as `invalid_filters` or `server_timeout`.
        - `code` string, required: Machine-readable error code
        - `title` string, required: Human-readable error description
      - `results` object[]: Per-company results. Present only for completed `preview` runs; regular runs write their values to the custom field instead. A scalar preview returns `score` and `reason`; a contacts preview (of a `contact_collection` field, or a prompt-only preview with `output_type: contact_collection`) returns `contacts` instead.
        - `company_id` string, required: The company the result is for
        - `company_name` string, nullable, required: The company's name, on every preview result. `null` when no name is known for the company. On a contacts preview it is truncated so that its JSON-encoded form is at most 40 bytes, not counting the enclosing quotes. On a contacts preview, an account without the `target` entitlement gets the name masked: its first three characters followed by one `*` per remaining character, as in company search results.
        - `contacts` ContactPreviewV1[]: The contacts the AI selected for this company. Present only on a contacts preview, in place of `score` and `reason`. When the AI finds no contacts for a company, the array is empty and `outcome` is still `success`. Contact details are not revealed by a preview, so only the identifying fields of each contact are returned.
          - `attributes` object, required
            - `full_name` string, nullable, required: The contact's display name. `null` when the source has none.
            - `position` object, nullable, required: The contact's position within the company. `null` when the contact has no known job title; otherwise `title` is always a string.
              - …
          - `id` string, required: The Leadfeeder contact ID.
          - `type` 'contact_preview', required: The type of the object. A preview carries a subset of the contact resource, so it has its own type.
        - `outcome` 'success' | 'no_data', required: Whether the AI produced an answer for this company
        - `reason` string: The AI's explanation for the answer
        - `score` unknown
      - `status` 'running' | 'completed' | 'failed', required: Current status of the job
      - `summary` object: Record processing summary
        - `failed` integer: Records that failed enrichment
        - `succeeded` integer: Records enriched successfully
        - `total` integer: Total records to process
    - `id` string, required: Unique job identifier
    - `type` string, required
  - `meta` object, required
    - `request_id` string, required: A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `401`: Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403`: Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `404`: The job wasn't found: the ID is unknown, the job has expired, it belongs to another account, or it is another kind of job.
- `429`: Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500`: Internal server error

## Changes

> 46 revisions in range; 1 not diffed.

- **2026-11-03** `686d4e39eb05`: 1 info
  - added the optional property `data/attributes/configuration/advanced_search` to the response with the `200` status
- **2026-10-23** `cfe89c1fc59d`: 1 breaking
  - the `data/attributes/credits/consumed` response's property type changed from `integer` to `number` for status `200`
- **2026-10-21** `a1970eac18e7`: 4 info
  - added the optional property `data/attributes/results/items/contacts` to the response with the `200` status
  - the response property `data/attributes/results/items/company_id` became required for the status `200`
  - the response property `data/attributes/results/items/outcome` became required for the status `200`
  - added the required property `data/attributes/results/items/company_name` to the response with the `200` status
- **2026-09-18** `5d15ed543ab8`: 1 breaking
  - the `data/attributes/credits/estimated` response's property type changed from `integer` to `number` for status `200`
- **2026-09-03** `ac752c6c2be0`: 5 info
  - added the optional property `errors/items/source` to the response with the `401` status
  - added the optional property `errors/items/source` to the response with the `403` status
  - added the optional property `errors/items/source` to the response with the `404` status
  - added the optional property `errors/items/source` to the response with the `429` status
  - …1 more

[Operation history](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/changes/v1/companies/enrichment-jobs/:job_id/get.md)

---

[API](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api.md) - [All operations](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/revisions/686d4e39eb05?raw)