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

```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()
```

### Batch retrieval by IDs

```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();
```

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