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

# List Lead Lists

> List every lead list in your Tuco workspace with its lead count — the source of the listId used when creating leads or running a bulk availability check.

<Note>
  A **list** owns leads. `listId` is what you pass to
  [`POST /api/leads`](/api-reference/endpoint/create) to file new leads somewhere specific, and to
  [`POST /api/leads/check-availability`](/api-reference/endpoint/bulk-check-availability) to check a
  whole list at once. These endpoints are how you get a `listId` without opening the dashboard.
</Note>

Returns every list in the workspace, **newest first**. No query parameters.

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

***

## Example

```bash theme={null}
curl "https://app.tuco.ai/api/lists" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx"
```

### Success (`200 OK`)

```json theme={null}
{
  "lists": [
    {
      "_id": "6aab49a066aa3784fa345a0a",
      "name": "Close Import",
      "description": "Contacts imported from Close",
      "workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur",
      "createdByUserId": "user_34tKD7C7oYWFSBH4JBvbSgO8de5",
      "leadCount": 4,
      "createdAt": "2026-09-17T02:00:00.189Z",
      "updatedAt": "2026-09-21T16:50:19.878Z"
    }
  ]
}
```

<Note>
  The **Quick Sends** list is created on the first call if it does not exist, so this endpoint never
  returns an empty array. Quick Sends is where leads go when you send to a phone number that has no
  saved lead yet, and when you omit `listId` on [`POST /api/leads`](/api-reference/endpoint/create).
</Note>

## Response

<ResponseField name="lists" type="object[]">
  Every list in the workspace, newest first.

  <Expandable title="List fields">
    <ResponseField name="_id" type="string">The list id. This is the `listId` other endpoints take.</ResponseField>
    <ResponseField name="name" type="string">List name. Unique within the workspace.</ResponseField>
    <ResponseField name="description" type="string">Optional description.</ResponseField>
    <ResponseField name="leadCount" type="number">How many leads the list holds.</ResponseField>
    <ResponseField name="createdByUserId" type="string">Clerk user id of whoever created it.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

***

## Errors

| Status | When | Body |
| - | - | - |
| `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` |
| `429` | More than 120 requests/min for this workspace | `{ "error": "Rate limit exceeded" }` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.