# List leads (/api-reference/leads/listLeads)

## GET /api/v1/leads/

Operation ID: `listLeads`
List leads
Newest first by default. Page with `page` and `limit`, or for deep lists pass `cursor` (empty first, then `nextCursor`): cursor pages skip the count and stay fast. Without `cursor` matches are counted up to 10,000 unless `includeTotal=true`.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `page` | query | no | Page number, from 1. Ignored when `cursor` is sent. |
| `limit` | query | no | Items per page, up to 200. |
| `search` | query | no | Matches part of the name, phone, email, company, title or external id. |
| `status` | query | no | Only leads with this pipeline status key (your workspace's statuses). |
| `leadSourceId` | query | no | Only leads from this lead source. |
| `campaignId` | query | no | Only leads in this campaign. |
| `dateFilter` | query | no | Created since 00:00 UTC today (`today`), or since 00:00 UTC 7 days ago (`week`) or 30 days ago (`month`). `all` (or no value) applies no date filter. |
| `sortBy` | query | no |  |
| `sortOrder` | query | no |  |
| `includeStats` | query | no | Add `stats` (total, byStatus, recentlyAdded, notCalled) for the filter. |
| `includeTotal` | query | no | Count every match exactly. By default the count stops at 10,000 (`pagination.totalCapped` says when there are more). |
| `cursor` | query | no | Empty for the first page, then the previous response's `nextCursor`. Only with the default sort (newest first); skips the count. |
| `assignedTo` | query | no | `me`, `unassigned`, or a team member's user ID. |
| `tag` | query | no | Only leads with this tag. |

### Responses

#### 200 OK

Example (example):

```json
{
  "hasMore": false,
  "leads": [
    {
      "attributes": {
        "city": "Pune"
      },
      "callAttempts": 0,
      "callStatus": "not_called",
      "campaignIds": [],
      "campaignNames": [],
      "company": "Rao Traders",
      "createdAt": "2026-11-15T10:00:00+00:00",
      "dncOptOut": false,
      "email": "asha@example.com",
      "id": "6f1c2a9e-3b7d-4c55-9a0e-1d2f3a4b5c6d",
      "name": "Asha Rao",
      "phone": "+919876543210",
      "source": "website",
      "status": "new",
      "tags": [],
      "title": "Owner",
      "updatedAt": "2026-11-15T10:00:00+00:00"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "hasNextPage": false,
    "hasPreviousPage": false,
    "itemsPerPage": 25,
    "totalCapped": false,
    "totalItems": 1,
    "totalPages": 1
  },
  "success": true
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 422 Invalid parameters: `parameter_invalid`.

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
