> ## Documentation Index
> Fetch the complete documentation index at: https://docs.freshtalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List lists

> Return every list visible to the authenticated organization, including generated default lists.

Returns all lists for the API-key's organization. The Gateway calls its default-list synchronizer before reading, so generated origin/Target lists and their current member counts can be materialized or refreshed as part of this request. A list `id` is a UUID; other list routes also accept a case-insensitive list name.

This endpoint has no query parameters and is **not paginated**. It returns every list in `data`, ordered with default lists first and then by the Gateway's stable default-list ordering. `meta.next` is never returned.

<Note>No `limit` parameter is supported. The endpoint returns all lists.</Note>

## Response schema

`data` is an array of list objects:

| Field                      | Type                        | Nullability and meaning                                     |
| -------------------------- | --------------------------- | ----------------------------------------------------------- |
| `id`                       | string (UUID)               | Never null.                                                 |
| `name`                     | string                      | Never null.                                                 |
| `description`              | string                      | `null` when no description is stored.                       |
| `is_default`               | boolean                     | `true` for Gateway-managed origin/Target lists.             |
| `default_key`              | string                      | `null` for custom lists; a generated-list key when present. |
| `source_watch_id`          | string (UUID)               | `null` when the list is not sourced from a Target/watch.    |
| `member_count`             | integer                     | Count of memberships in this list, including zero.          |
| `created_at`, `updated_at` | string (ISO 8601 timestamp) | Never null.                                                 |

`meta.count` is the number of objects in `data`. There is no cursor, offset, page size, or next URL.

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "hot",
        "description": null,
        "is_default": false,
        "default_key": null,
        "source_watch_id": null,
        "member_count": 0,
        "created_at": "2026-09-07T10:00:00.000Z",
        "updated_at": "2026-09-07T10:00:00.000Z"
      }
    ],
    "meta": {
      "count": 1
    }
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --fail-with-body --max-time 30 "https://api.freshtalent.ai/v1/lists" \
    -H "Authorization: Bearer $FRESHTALENT_API_KEY"
  ```

  ```js JavaScript (native fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.freshtalent.ai/v1/lists", {
    signal: AbortSignal.timeout(30_000), headers: { Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}` },
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  const body = await response.json();
  console.log(body.data, body.meta.count);
  ```

  ```python Python (stdlib) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import json
  import os
  from urllib.request import Request, urlopen

  request = Request(
      "https://api.freshtalent.ai/v1/lists",
      headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
  )
  with urlopen(request, timeout=30) as response:
      body = json.load(response)
  print(body["data"], body["meta"]["count"])
  ```
</RequestExample>

## Errors and recovery

* `400` (`invalid_request`): when using the platform API key, provide a valid `X-FreshTalent-Org-Id` UUID.
* `401` (`unauthorized`): provide a valid `Authorization: Bearer ...` API key.
* `402` (`payment_required`): the organization's trial or paid access is locked; restore entitlement and retry.
* `429`: respect the rate limit and retry with backoff.
* `500` or another `5xx`: the read may have failed while default lists were being synchronized; retry with backoff, then reconcile with a fresh `GET /lists`.

A successful `200` is safe to retry. Because this read can refresh generated lists, a caller should not treat the request as a completely side-effect-free database read.

## Related

| Method   | Path         | Purpose                                    |
| -------- | ------------ | ------------------------------------------ |
| `POST`   | `/lists`     | [Create list](/api-reference/lists/create) |
| `GET`    | `/lists/:id` | [Get list](/api-reference/lists/get)       |
| `DELETE` | `/lists/:id` | [Delete list](/api-reference/lists/delete) |

**Next:** [Create list](/api-reference/lists/create) or [Get list](/api-reference/lists/get).