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

# Get Batch Remove from List Job

`GET /v1/lists/batch-remove-from-list-jobs/{job_id}`

## Request

- Base URL: `https://api.leadfeeder.com`
- URL: `https://api.leadfeeder.com/v1/lists/batch-remove-from-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 remove-from-list job created via `POST /v1/lists/batch-remove-from-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_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 remove-from-list job status retrieved

- object
  - `data` BatchRemoveFromListJobV1, 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_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't change the list when the job runs, for example because it is shared with you for viewing only, or because you lost access to it. - `list_read_only`, "This list is read-only and its members cannot be modified": the list is read-only, such as a revealed, CRM or custom feed list. - `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 the list, or a list in your filters, is deleted or no longer shared with you before the job runs, or `server_timeout` when it takes too long. A failed job reports no counts. Members it removed before failing stay off the list.
        - `code` string, required: Machine-readable error code
        - `title` string, required: Human-readable error description
      - `results` object[]: Per-item outcome of the remove 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.
        - `id` string, required: The Dealfront company or contact ID that was processed.
        - `status` 'removed' | 'not_found', required: Indicative, best-effort status for this item: the job doesn't check whether the item was on the list.
        - `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 after the job applied. Present only when `status` is `completed`. The outcome counts are best-effort: they aggregate the indicative per-item statuses and are not a guaranteed-exact classification.
        - `failed_count` integer: Total number of items that did not complete successfully. Always 0 for an `items` or `advanced_search` job: when the list's members can't be changed, the job fails instead.
        - `list_size_after` integer: Number of members on the list after the job applied.
        - `not_found` integer: Number of references whose ID isn't a number. Always 0 for a job created from a search selection.
        - `not_present` integer: Number of members not in the list (remove no-op). Always 0: items that weren't on the list are counted in `removed`.
        - `removed` integer: Number of members removed, counting every item whose ID is a number, whether or not it was on the list. For a job created from an `advanced_search` selection, the matching companies the job asked to remove, not counting the excluded IDs.
        - `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-11-03** `4cf93a08d7a3`: 2 info
  - removed the `not_present` enum value from the `data/attributes/results/items/status` response property for the response status `200`
  - 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-remove-from-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)