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

# DeltaLead API Cursor-Based Pagination for List Endpoints

> DeltaLead list endpoints use cursor-based pagination. Supply the cursor and limit parameters to step through leads, conversations, and agent records.

All DeltaLead list endpoints — `GET /leads`, `GET /conversations`, and `GET /agents` — return paginated results using cursor-based pagination. Rather than page numbers, the API returns an opaque `next_cursor` value that encodes your position in the result set. Pass it back as the `cursor` query parameter to fetch the next page. When `has_more` is `false`, you have retrieved all available records.

## Pagination Parameters

<ParamField query="limit" type="integer" default="20">
  The number of results to return per page. Minimum: `1`. Maximum: `100`. Defaults to `20` if omitted.
</ParamField>

<ParamField query="cursor" type="string">
  An opaque cursor string returned in the previous response's `pagination.next_cursor` field. Omit this parameter to start from the beginning of the result set.
</ParamField>

## Paginated Response Format

Every list endpoint wraps results in a `data` array and includes a `pagination` object:

```json theme={null}
{
  "data": [
    { "id": "lead_abc123", "..." }
  ],
  "pagination": {
    "limit": 20,
    "next_cursor": "eyJpZCI6ImxlYWRfYWJjMTIzIn0",
    "has_more": true
  }
}
```

<ResponseField name="data" type="array">
  The array of resource objects for the current page.
</ResponseField>

<ResponseField name="pagination.limit" type="integer">
  The page size used for this response — mirrors the `limit` you requested.
</ResponseField>

<ResponseField name="pagination.next_cursor" type="string">
  Pass this value as the `cursor` query parameter in your next request to retrieve the following page. This field is `null` when `has_more` is `false`.
</ResponseField>

<ResponseField name="pagination.has_more" type="boolean">
  `true` if additional pages exist beyond this one; `false` when you have reached the end of the result set.
</ResponseField>

## Iterating All Pages

The example below fetches every lead in your account by looping until `has_more` is `false`:

```javascript Fetch all leads theme={null}
async function fetchAllLeads(apiKey) {
  const leads = [];
  let cursor = null;

  do {
    const url = new URL('https://platform-api.deltalead.ai/v1/leads');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, { headers: { 'X-API-Key': apiKey } });
    const page = await res.json();

    leads.push(...page.data);
    cursor = page.pagination.has_more ? page.pagination.next_cursor : null;
  } while (cursor);

  return leads;
}
```

<Note>
  Cursors are opaque strings — do not attempt to parse, decode, or construct them manually. Their internal format may change between API versions without notice. Always use the `next_cursor` value exactly as returned in the response.
</Note>

## Filtering and Sorting with Pagination

You can combine pagination parameters with any filtering or sorting parameters supported by a given endpoint. Filtering parameters are encoded into the cursor, so you do not need to repeat them on subsequent pages — only the `cursor` (and optionally `limit`) are required after the first request.

<Tip>
  Set `limit=100` when you need to fetch a large number of records. Using the maximum page size minimises the total number of HTTP round-trips required, which reduces both latency and the risk of hitting rate limits. See [Rate Limits](/en/api-reference/introduction#rate-limits) for details.
</Tip>