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

# Get Leads Endpoint

> Retrieve leads for a workspace with optional list, search, and pagination filters

## Endpoint

* **Method**: `GET`
* **Path**: `/api/leads`

This endpoint returns leads in the active workspace, matching what you see in the Tuco UI.

***

## Query Parameters

* `listId` (`string`, optional) – restrict to a specific Tuco list.
* `search` (`string`, optional) – case‑insensitive search on name, email, phone, or company.
* `page` (`number`, optional, default `1`) – page number.
* `limit` (`number`, optional, default `50`) – page size.

Example:

```bash theme={null}
GET /api/leads?listId=507f1f77bcf86cd799439011&search=john&page=1&limit=50
Authorization: Bearer <token>
```

***

## Response

```json theme={null}
{
  "leads": [
    {
      "_id": "667f1f77bcf86cd799439012",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+12025551234",
      "companyName": "Acme Corp",
      "jobTitle": "CEO",
      "listId": "507f1f77bcf86cd799439011",
      "workspaceId": "org_123",
      "createdAt": "2025-10-14T10:30:00Z",
      "updatedAt": "2025-10-14T10:30:00Z"
    }
  ],
  "lists": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Prospects – October",
      "workspaceId": "org_123"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 1,
    "totalPages": 1
  }
}
```

No hidden changes are applied to your data by reading; this endpoint is read‑only from your point of view. Errors such as missing auth (`401`) or invalid query parameters (`400`) are returned with clear JSON messages.