---
title: "Remove Records from a List"
method: POST
path: "/labels/remove_entity_ids_from_label_names"
tags: ["Miscellaneous"]
---

# Remove Records from a List

`POST /labels/remove_entity_ids_from_label_names`

This endpoint doesn't consume Apollo credits. Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing).

A <a href="https://knowledge.apollo.io/hc/en-us/articles/4409728608525-Create-and-Use-a-List" target="_blank">list</a> is a saved group of contacts or accounts in Apollo that you can organize, action, and track together.<br><br>Use the Remove Records from a List endpoint to remove contacts or accounts from one or more lists, referencing the lists by name. Removing records from a list doesn't delete the records themselves — it only removes them from the specified lists.<br><br>Provide the record IDs in `entity_ids` and the list names in `label_names`. To find record IDs, use the <a href="https://docs.apollo.io/reference/search-for-contacts">Search for Contacts</a> or <a href="https://docs.apollo.io/reference/search-for-accounts">Search for Accounts</a> endpoints.<br><br>If you provide no valid `entity_ids` or no `label_names`, the endpoint makes no changes and returns a `200` response with a confirmation message.

## Request body

- object
  - `entity_ids` string[], required — The Apollo IDs of the contacts or accounts to remove from the lists. IDs that aren't valid are ignored.<br><br>Example: `["66e34b81740c50074e3d1bd4"]`
  - `label_names` string[], required — The names of the lists to remove the records from.<br><br>Example: `["Conference 2024 - Maui"]`
  - `modality` 'contacts' | 'accounts', required — The type of records referenced by `entity_ids`. Must be `contacts` or `accounts`.
  - `async` boolean — Controls whether the request is processed synchronously or in the background. <ul><li>`false` (default): Apollo processes the request during the API call and returns the updated lists. A synchronous request must finish within the API's 5-minute (300-second) request timeout, so a large `entity_ids` batch can time out.</li><li>`true`: Apollo processes the work in the background and immediately returns an `entity_progress_job` object — instead of the updated lists — that you can poll for progress. Use this for batches large enough to risk the 5-minute timeout.</li></ul>

## Response `200`

200

- object
  - `labels` object[]
    - `id` string
    - `modality` string
    - `cached_count` integer
    - `name` string
    - `created_at` string
    - `updated_at` string
    - `user_id` string
    - `book_of_business` boolean, nullable
  - `message` string
  - `entity_progress_job` object — Returned instead of `labels` when `async` is `true`. Represents the background job processing the request; poll it to track progress.
    - `id` string
    - `user_id` string, nullable
    - `job_type` string
    - `entity_ids` string[]
    - `params` object
    - `progress` number — `-1` before processing starts, a fraction while in progress, and `1` when complete.
    - `batch_size` integer, nullable

## Other responses

- `401` — 401
- `403` — 403
- `422` — 422
- `429` — 429

---

[API](https://skmtc.dev/apollo/apis/apollo-rest-api.md) · [All operations](https://skmtc.dev/apollo/apis/apollo-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/apollo/apollo-rest-api/revisions/c715a05fa6e2/schema)