> ## 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 |


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