Pagination - Chataigne Docs

All Chataigne list endpoints return a consistent list envelope and use cursor-based pagination. Cursors are existing resource IDs, so paging stays stable even as records are created or deleted while you iterate.

The list envelope

Every list response uses the same shape:

List response

{
  "object": "list",
  "data": [
    { "id": "cced7db5-4e5b-41d2-ac44-90616487dd2c...", "object": "special_closing", "...": "..." },
    { "id": "17d914d1-6e92-4ffd-a27a-c4df5d6f1cca...", "object": "special_closing", "...": "..." }
  ],
  "has_more": true,
  "url": "/v1/locations/909e4a52-ec63-45ae-a89c-1074ce71f8d1.../special_closings"
}

string

Always "list" for list responses.

array

The array of resource objects for this page, ordered by created_at by default.

boolean

true when more records exist beyond this page. Use it as your stop condition when iterating—do not rely on data.length.

string

The path of the list endpoint that produced this response.

Parameters

integer

default:"10"

Number of records to return per page. Must be between 1 and 100.

string

A resource id cursor. Returns the page of records immediately after this object in the default created_at order. Use it to page forward.

string

A resource id cursor. Returns the page of records immediately before this object in the default created_at order. Use it to page backward.

starting_after and ending_before are mutually exclusive. Sending both in the same request returns 400 invalid_request_error.

Paging forward

To walk a list from the beginning, request the first page, then pass the last item’s id as starting_after until has_more is false.

# First page
curl https://server.chataigne.ai/v1/locations/00fcd882-db86-47d8-a9ea-65263919906c/special_closings?limit=2 \
  -H "x-api-key: ch_org_live_5fK..."

# Next page — pass the last id from the previous page
curl "https://server.chataigne.ai/v1/locations/00fcd882-db86-47d8-a9ea-65263919906c/special_closings?limit=2&starting_after=03d51022-069c-4af9-a946-d3bef8624c4c" \
  -H "x-api-key: ch_org_live_5fK..."

const BASE_URL = "https://server.chataigne.ai";
const headers = { "x-api-key": process.env.CHATAIGNE_API_KEY };

/**
 * Fetch a single page of special closings for a location.
 */
async function listSpecialClosings({ locationId, limit = 100, startingAfter }) {
  const params = new URLSearchParams({ limit: String(limit) });
  if (startingAfter) params.set("starting_after", startingAfter);
  const res = await fetch(
    `${BASE_URL}/v1/locations/${locationId}/special_closings?${params}`,
    { headers },
  );
  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  return res.json();
}

/**
 * Iterate every special closing for a location, page by page.
 */
async function getAllSpecialClosings(locationId) {
  const all = [];
  let startingAfter;
  while (true) {
    const page = await listSpecialClosings({ locationId, startingAfter });
    all.push(...page.data);
    if (!page.has_more) break;
    startingAfter = page.data[page.data.length - 1].id; // cursor = last id
  }
  return all;
}

const closings = await getAllSpecialClosings("00fcd882-db86-47d8-a9ea-65263919906c");
console.log(`Fetched ${closings.length} special closings`);

Set limit to its maximum of 100 when bulk-syncing to minimize round trips. Keep it small for interactive UIs.

Paging backward

To page toward older records—for example, when scrolling up in a UI—use ending_before with the first item’s id from the current page.

curl

curl "https://server.chataigne.ai/v1/locations/00fcd882-db86-47d8-a9ea-65263919906c/special_closings?limit=2&ending_before=701a5288-5291-4d08-a366-bcfad8b0ece3" \
  -H "x-api-key: ch_org_live_5fK..."

Timestamp filters

List endpoints accept timestamp filters to narrow results to a window. Combine them freely with the pagination cursors and limit.

string

Only return records created strictly after this ISO 8601 timestamp.

string

Only return records created strictly before this ISO 8601 timestamp.

string

Only return records updated strictly after this ISO 8601 timestamp.

string

Only return records updated strictly before this ISO 8601 timestamp.

All timestamps are ISO 8601 in UTC (e.g. 2026-05-01T00:00:00Z). Results remain ordered by created_at.

curl

# Special closings created in May 2026, newest-friendly bulk page
curl -G "https://server.chataigne.ai/v1/locations/00fcd882-db86-47d8-a9ea-65263919906c/special_closings" \
  -H "x-api-key: ch_org_live_5fK..." \
  --data-urlencode "created_after=2026-05-01T00:00:00Z" \
  --data-urlencode "created_before=2026-06-01T00:00:00Z" \
  --data-urlencode "limit=100"

Node.js

const params = new URLSearchParams({
  created_after: "2026-05-01T00:00:00Z",
  created_before: "2026-06-01T00:00:00Z",
  limit: "100",
});
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/00fcd882-db86-47d8-a9ea-65263919906c/special_closings?${params}`,
  { headers: { "x-api-key": process.env.CHATAIGNE_API_KEY } },
);
const page = await res.json();

Timestamp filters apply to the same set of records the cursor walks. When using created_after/created_before with starting_after, keep the filter values constant across every page of a single iteration so the cursor stays consistent.

Best practices

Iterate on has_more, not on counts. A full page (data.length === limit) can still be the last page.
Treat cursors as opaque. Always pass back an id from a previous response; never construct or guess one.
Pick one direction. Use starting_after or ending_before—never both.
Carry the same filters across pages within a single iteration to keep the cursor stable.

List endpoints

See which resources support listing—organizations, locations, and special closings—and their filterable fields.

​The list envelope

​Parameters

​Paging forward

​Paging backward

​Timestamp filters

​Best practices

List endpoints

The list envelope

Parameters

Paging forward

Paging backward

Timestamp filters

Best practices