Pagination

All list endpoints in the Clarky API return paginated results. Pagination is page-based — you ask for a specific page and a page size, and the response tells you how many pages there are in total.

Query parameters

integer

default:"1"

The 1-indexed page number to fetch.

integer

default:"25"

Number of items per page. Maximum is 100. Requests above the maximum return validation_error.

Response shape

Every list endpoint wraps results in data (the items for the current page) and pagination (metadata about the pagination state).

{
  "data": [
    { "id": "c_01HXYZ...", "first_name": "Ada" },
    { "id": "c_01HXYZ...", "first_name": "Grace" }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total": 142,
    "total_pages": 6
  }
}

integer

The current page number (1-indexed).

integer

Number of items returned per page.

integer

Total number of items across every page.

integer

Total number of pages. total_pages is Math.ceil(total / page_size).

Examples

Fetch the first page

curl "https://clarky.ai/api/v1/contacts?page=1&page_size=25" \
  -H "Authorization: Bearer ck_live_example"

Fetch a larger page

curl "https://clarky.ai/api/v1/contacts?page_size=100" \
  -H "Authorization: Bearer ck_live_example"

Iterate every page

async function fetchAllContacts(apiKey) {
  const all = [];
  let page = 1;

  while (true) {
    const res = await fetch(
      `https://clarky.ai/api/v1/contacts?page=${page}&page_size=100`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    const { data, pagination } = await res.json();
    all.push(...data);

    if (page >= pagination.total_pages) break;
    page += 1;
  }

  return all;
}

For large backfills, prefer page_size=100 to minimize round-trips, and respect the rate limits by backing off when you see 429 responses.

Endpoints that don’t paginate

A small number of endpoints return collections without pagination because the result set is bounded — for example, stages within a pipeline. These return { "data": [...] } with no pagination object. The shape is documented per-endpoint.

Single-resource responses

For endpoints that return a single resource (e.g. GET /contacts/{id}), the response is just { "data": { ... } } — no pagination object.

{
  "data": {
    "id": "c_01HXYZ...",
    "first_name": "Ada"
  }
}

Getting Started

Resources

Query parameters

Response shape

Examples

Fetch the first page

Fetch a larger page

Iterate every page

Endpoints that don’t paginate

Single-resource responses

​Query parameters

​Response shape

​Examples

​Fetch the first page

​Fetch a larger page

​Iterate every page

​Endpoints that don’t paginate

​Single-resource responses

Query parameters

Response shape

Examples

Fetch the first page

Fetch a larger page

Iterate every page

Endpoints that don’t paginate

Single-resource responses