# Get a list

Source: https://docs.emelia.io/docs/lists/get-list

Guide: [Lists & contacts](https://docs.emelia.io/docs/lists.md)

`GET https://api.emelia.io/lists/list/{listId}`

Returns one list with its counters.

The counters are denormalized: `numberOfEmails` and `numberOfPhones` count the contacts that had an email or a `phone` (not `mobilePhone`) when they were added, and are recomputed only at the end of a find-email or find-phone run. They are not updated when a contact is edited: treat them as indicative and use `GET /lists/list/{listId}/rows` for exact data.

`enrichmentRun` is non-null while a bulk job runs on the list (find email, find phone, verify email, column normalization, file import, CRM sync). While it is set, starting another bulk job on the list returns 409.

## Authentication

Send your API key in the `Authorization` header: `Authorization: <your API key>`.

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `listId` | string | yes | List id (24-character ObjectId). |

## Example request

**cURL**

```bash
curl -X GET "https://api.emelia.io/lists/list/65f1a2b3c4d5e6f760f68df4" \
  -H "Authorization: $EMELIA_API_KEY"
```

**JavaScript**

```js
const response = await fetch('https://api.emelia.io/lists/list/65f1a2b3c4d5e6f760f68df4', {
  method: 'GET',
  headers: { Authorization: process.env.EMELIA_API_KEY },
});
console.log(await response.json());
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.emelia.io/lists/list/65f1a2b3c4d5e6f760f68df4",
    headers={"Authorization": os.environ["EMELIA_API_KEY"]},
)
print(response.json())
```

## Responses

### 200: The list.

| Field | Type | Required | Description |
|---|---|---|---|
| `_id` | string | yes |  |
| `name` | string | yes |  |
| `fileId` | string or null | no |  |
| `source` | string | yes |  |
| `status` | string | yes |  |
| `companiesOnly` | boolean | yes |  |
| `numberOfContacts` | integer | yes |  |
| `numberOfEmails` | integer | yes |  |
| `numberOfPhones` | integer | yes |  |
| `numberOfLinkedins` | integer | no |  |
| `emailFindRunAt` | string or null (date-time) | no |  |
| `phoneFindRunAt` | string or null (date-time) | no |  |
| `enrichmentRun` | object or null | yes |  |
| `hubspotIntegration` | object or null | yes |  |
| `pipedriveIntegration` | object or null | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `updatedAt` | string (date-time) | yes |  |

```json
{
  "_id": "66f1c0ffee5a7d3b2c4e8a10",
  "name": "Acme prospects Q4",
  "fileId": null,
  "source": "API",
  "status": "mapped",
  "companiesOnly": false,
  "numberOfContacts": 42,
  "numberOfEmails": 40,
  "numberOfPhones": 12,
  "numberOfLinkedins": 38,
  "emailFindRunAt": null,
  "phoneFindRunAt": null,
  "enrichmentRun": null,
  "hubspotIntegration": null,
  "pipedriveIntegration": null,
  "createdAt": "2026-10-01T09:12:44.000Z",
  "updatedAt": "2026-10-03T16:40:02.000Z"
}
```

### 400: The list id is not a valid ObjectId.

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | English, human-readable message. |
| `code` | string | no | Stable error code, when available (for example `PAYLOAD_TOO_LARGE`, `INVALID_JSON`, `export_too_large`, `companies_only`, `enrichment_running`). |
| `params` | object | no |  |
| `error` | string | no | Raw internal message (unexpected errors only). |

```json
{
  "message": "Invalid list id"
}
```

### 401: Missing, unknown or disabled API key, or the account of the key no longer exists. Note the body shape: `error` and `code`, not `message`.

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | string | yes |  |
| `code` | enum: `AUTH_REQUIRED`, `ACCOUNT_NOT_FOUND` | yes |  |

```json
{
  "error": "string",
  "code": "AUTH_REQUIRED"
}
```

### 404: The list does not exist or belongs to another account.

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | English, human-readable message. |
| `code` | string | no | Stable error code, when available (for example `PAYLOAD_TOO_LARGE`, `INVALID_JSON`, `export_too_large`, `companies_only`, `enrichment_running`). |
| `params` | object | no |  |
| `error` | string | no | Raw internal message (unexpected errors only). |

```json
{
  "message": "List not found"
}
```

### 500: Unexpected server error. `error`, when present, is a raw internal message: do not parse it. Retry later.

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | English, human-readable message. |
| `code` | string | no | Stable error code, when available (for example `PAYLOAD_TOO_LARGE`, `INVALID_JSON`, `export_too_large`, `companies_only`, `enrichment_running`). |
| `params` | object | no |  |
| `error` | string | no | Raw internal message (unexpected errors only). |

```json
{
  "message": "Hmm... Something went wrong. Please try again later."
}
```