---
title: "Get Batch Add to List Job"
method: GET
path: "/v1/lists/batch-add-to-list-jobs/{job_id}"
tags: ["Lists", "v1"]
---

# Get Batch Add to List Job

`GET /v1/lists/batch-add-to-list-jobs/{job_id}`

## Request

- Base URL: `https://api.leadfeeder.com`
- URL: `https://api.leadfeeder.com/v1/lists/batch-add-to-list-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: `lists:read`

Retrieve the status of a batch add-to-list job created via `POST /v1/lists/batch-add-to-list-jobs`.

While `status` is `running`, `results` and `summary` are omitted. Once `status` becomes `completed`, `results` carries the per-item outcome and `summary` carries the per-outcome counts (including `failed_count`) together with `list_size_before` and `list_size_after`. A job created from a search selection reports `summary` counts only — no per-item `results`. On `failed`, `errors` describes the failure.

Jobs are kept for 7 days after creation.

Credit Note: This endpoint does not consume credits.

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

## Path parameters

- `job_id` string, required

## Query parameters

- `account_id` string, required

## Response `200`

Batch add-to-list job status retrieved

- object
  - `data` BatchAddToListJobV1, 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` union, required: Echoed request configuration. Present at every status, from the moment the job is created. Carries the `items` array (each repeated item once) or the search selection the job was created with — exactly one of the two.
        - object
          - `advanced_search` object: The advanced-search selection supplied in the originating request.
            - `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.
              - …
            - `page` object: Bounds how many of the matching companies are selected.
              - …
            - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering.
              - …
          - `items` object[], required: The references supplied in the originating request, each repeated item once.
            - `id` string, required: The Dealfront entity ID.
            - `type` 'company' | 'contact', required: The entity type (e.g. `company` or `contact`).
          - `list_id` string, required: The scope-prefixed list identifier the job operates on (e.g. `company_123` or `contact_456`).
        - object
          - `advanced_search` object, required: The advanced-search selection supplied in the originating request.
            - `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.
              - …
            - `page` object: Bounds how many of the matching companies are selected.
              - …
            - `sort` object: Ordering applied to the matching companies. Omit to use the default ordering.
              - …
          - `items` object[]: The references supplied in the originating request, each repeated item once.
            - `id` string, required: The Dealfront entity ID.
            - `type` 'company' | 'contact', required: The entity type (e.g. `company` or `contact`).
          - `list_id` string, required: The scope-prefixed list identifier the job operates on (e.g. `company_123` or `contact_456`).
      - `created_at` string, date-time, required: When the job was created.
      - `errors` object[]: Present only when `status` is `failed`, with one error: - `list_capacity_exceeded`, "Applying these operations would exceed the maximum list size": the members would take the list past 1,000,000. - `list_not_found`, "The list could not be found": the list no longer exists when the job runs. - `list_access_denied`, "The list is no longer accessible": you can no longer change the list when the job runs, for example because you lost access to it. - `job_exhausted_retries`, "Membership update failed after exhausting retries": temporary errors persisted. Create the job again. - `job_failed`, "Membership update could not be applied": any other error. - For a job created from a search selection, the search's own code and title, such as `invalid_filters` when it rejects the filter tree, `invalid_parameter` when it rejects the sort, `unprocessable_entity` when a list in the filters no longer exists, or `server_timeout` when it takes too long. A failed job reports no counts. Members it added before failing stay on the list.
        - `code` string, required: Machine-readable error code
        - `title` string, required: Human-readable error description
      - `results` object[]: Per-item outcome of the add job, in request order, each repeated item once. Present only when `status` is `completed` and the job was created with an explicit `items` array — a job created from a search selection reports `summary` counts only. Items that exist but couldn't be added are left out and counted in `summary.failed_count`.
        - `id` string, required: The Dealfront company or contact ID that was processed.
        - `status` 'added' | 'already_present' | 'not_found', required: What the job did with this item.
        - `type` 'company' | 'contact', required: The kind of entity this result item refers to.
      - `status` 'running' | 'completed' | 'failed', required: Current status of the job
      - `summary` object: Counts of items by outcome, plus the list size before and after the job applied. Present only when `status` is `completed`.
        - `added` integer: Number of members added. For a job created from a search selection, the matches added.
        - `already_present` integer: Number of members already in the list (add no-op). For a job created from a search selection, the matches that were already on the list.
        - `failed_count` integer: Total number of items that exist but couldn't be added, which `results` leaves out. Always 0 for a job created from a search selection, which counts them in `not_found`.
        - `list_size_after` integer: Number of members on the list after the job applied, counting every member.
        - `list_size_before` integer: Number of members on the list when the job was created, not counting the members whose company or contact record no longer exists.
        - `not_found` integer: Number of referenced entities that could not be found, including references whose ID isn't a number. For a job created from a search selection, matches that could not be added are counted here.
        - `scope_mismatch` integer: Number of references whose type did not match the list scope. Always 0: such a reference is rejected when the job is created.
    - `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
- `504`: Server timeout

## Changes

> 46 revisions in range; 1 not diffed.

- **2026-10-30** `8e37aaf0ccad`: 1 info
  - removed the `scope_mismatch` enum value from the `data/attributes/results/items/status` response property for the response status `200`
- **2026-10-28** `1344fb600ac2`: 2 breaking
  - the `data/attributes/configuration/advanced_search/allOf[subschema #1]/filters/items` response property's minItems was decreased from `1` to `0` for the response status `200`
  - the `data/attributes/configuration/advanced_search/allOf[subschema #1]/filters/items/items/oneOf[subschema #37: Group]/items` response property's minItems was decreased from `1` to `0` for the response status `200`
- **2026-10-06** `69e0c94ac1fd`: 1 info
  - added the optional property `data/attributes/configuration/advanced_search/allOf[subschema #1]/filters/items/items/oneOf[subschema #5: Geo Filter]/label` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/leadfeeder/apis/leadfeeder-public-api/changes/v1/lists/batch-add-to-list-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)