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

# List Leads

> Returns a paginated list of leads in your workspace.

# List Leads

Returns a paginated list of leads in your workspace. Supports search and filtering.

## Request

`GET /v1/leads`

### Query Parameters

| Parameter      | Type    | Required | Description                                                                                                                |
| -------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `page`         | integer | No       | Page number (default: 1)                                                                                                   |
| `per_page`     | integer | No       | Results per page, max 100 (default: 25)                                                                                    |
| `search`       | string  | No       | Search across name, email, phone, and company                                                                              |
| `status`       | string  | No       | Filter by status (`pending`, `calling`, `connected`, etc.)                                                                 |
| `campaign_id`  | uuid    | No       | Filter by campaign ID                                                                                                      |
| `call_outcome` | string  | No       | Filter by call outcome disposition                                                                                         |
| `ids`          | string  | No       | Comma-separated list of lead UUIDs for batch retrieval (max 100). When provided, pagination and other filters are ignored. |

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads?page=1&per_page=10&search=acme" \
    -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    page: "1",
    per_page: "10",
    search: "acme"
  });

  const response = await fetch(
    `https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads?${params}`,
    {
      headers: {
        "Authorization": "Bearer rchd_live_xxxxxxxxxxxx"
      }
    }
  );
  const { data, meta } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads",
      headers={"Authorization": "Bearer rchd_live_xxxxxxxxxxxx"},
      params={"page": 1, "per_page": 10, "search": "acme"}
  )
  result = response.json()
  ```
</CodeGroup>

### Batch retrieval by IDs

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads?ids=uuid1,uuid2,uuid3" \
    -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx"
  ```

  ```javascript JavaScript theme={null}
  const leadIds = ["uuid1", "uuid2", "uuid3"];
  const response = await fetch(
    `https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads?ids=${leadIds.join(",")}`,
    { headers: { "Authorization": "Bearer rchd_live_xxxxxxxxxxxx" } }
  );
  const { data } = await response.json();
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acme.com",
      "phone": "+33612345678",
      "company_name": "Acme Corp",
      "status": "pending",
      "call_outcome": null,
      "total_calls": 0,
      "created_at": "2026-03-21T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 1
  }
}
```

### Response Fields

| Field           | Type    | Description                    |
| --------------- | ------- | ------------------------------ |
| `data`          | array   | Array of lead objects          |
| `meta.page`     | integer | Current page number            |
| `meta.per_page` | integer | Items per page                 |
| `meta.total`    | integer | Total number of matching leads |