Skip to main content
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

​
page
integer
default:"1"
The 1-indexed page number to fetch.
​
page_size
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
  }
}
​
pagination.page
integer
The current page number (1-indexed).
​
pagination.page_size
integer
Number of items returned per page.
​
pagination.total
integer
Total number of items across every page.
​
pagination.total_pages
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"
  }
}