DeltaLead API Cursor-Based Pagination for List Endpoints

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

integer

default:"20"

The number of results to return per page. Minimum: 1. Maximum: 100. Defaults to 20 if omitted.

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.

Paginated Response Format

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

{
  "data": [
    { "id": "lead_abc123", "..." }
  ],
  "pagination": {
    "limit": 20,
    "next_cursor": "eyJpZCI6ImxlYWRfYWJjMTIzIn0",
    "has_more": true
  }
}

array

The array of resource objects for the current page.

integer

The page size used for this response — mirrors the limit you requested.

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.

boolean

true if additional pages exist beyond this one; false when you have reached the end of the result set.

Iterating All Pages

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

Fetch all leads

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;
}

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.

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.

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 for details.

Overview

Leads

Conversations

Agents

Webhooks

DeltaLead API Cursor-Based Pagination for List Endpoints

Paginated Response Format

Iterating All Pages

​Pagination Parameters

​Paginated Response Format

​Iterating All Pages

​Filtering and Sorting with Pagination

Pagination Parameters

Paginated Response Format

Iterating All Pages

Filtering and Sorting with Pagination