# List your lists

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

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

`GET https://api.emelia.io/lists/list`

Returns the contact lists of the account (top-level lists only: lists attached to a parent list are not returned).

Pagination is opt-in. Send `page` and/or `limit` to get the paginated envelope `{ items, total, page, pageSize, totalLeads }`. Without both parameters the endpoint returns a bare JSON array with ALL your lists, unpaginated, newest first, and every filter parameter is ignored. Integrations should always send `page` and `limit`.

To find which lists contain a person, pass `leadSearch` with a full email address (case-insensitive match) or a LinkedIn profile URL (matched on the profile handle, so trailing slashes and `www` do not matter). Any other value returns zero lists.

Each item is the stored list document. Besides the documented fields it can contain internal fields (column preferences, AI action settings, CRM integration settings, linked lists): do not rely on them.

## Authentication

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

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | Page number, starting at 1. Sending it switches the response to the paginated envelope. Default: `1`. Range: 1 to .... |
| `limit` | integer | no | Page size. Values above 100 are clamped to 100. Sending it switches the response to the paginated envelope. Default: `25`. Range: 1 to 100. |
| `search` | string | no | Case-insensitive substring of the list name. Paginated mode only. |
| `leadSearch` | string | no | Full email address or LinkedIn profile URL: only the lists containing this contact are returned. Paginated mode only. |
| `source` | string | no | Import source, exact value, case-insensitive. Values written by the service: `API` (created through this API), `Manual` (empty list created in the app), `CSV` (file import), `Sales Navigator` (LinkedIn scrap), `HubSpot`, `Pipedrive`, `Filter` (list created from a filtered selection). Paginated mode only. |
| `status` | enum: `mapped`, `pending mapping` | no | List status. Paginated mode only. |
| `tags` | string | no | Comma-separated tag ids: returns the lists carrying at least one of them. Paginated mode only. |
| `sortBy` | enum: `name`, `leads`, `emails`, `phones`, `createdAt` | no | Sort field: `leads`, `emails` and `phones` sort on the counters. Unknown values fall back to `createdAt`. Paginated mode only. Default: `"createdAt"`. |
| `sortDir` | enum: `asc`, `desc` | no | Sort direction. Any value other than `asc` sorts descending. Default: `"desc"`. |

## Example request

**cURL**

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

**JavaScript**

```js
const response = await fetch('https://api.emelia.io/lists/list', {
  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",
    headers={"Authorization": os.environ["EMELIA_API_KEY"]},
)
print(response.json())
```

## Responses

### 200: Paginated envelope when `page` or `limit` is sent, otherwise a bare array of all lists.

```json
{
  "items": [
    {}
  ],
  "total": 0,
  "page": 0,
  "pageSize": 0,
  "totalLeads": 0
}
```

### 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"
}
```

### 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."
}
```