Skip to main content
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—on both /v1 and /admin/v1—shares the same shape:
List response
{
  "object": "list",
  "data": [
    { "id": "scl_8Hk2...", "object": "special_closing", "...": "..." },
    { "id": "scl_3Qm9...", "object": "special_closing", "...": "..." }
  ],
  "has_more": true,
  "url": "/v1/locations/loc_9aZ.../special_closings"
}
​
object
string
Always "list" for list responses.
​
data
array
The array of resource objects for this page, ordered by created_at by default.
​
has_more
boolean
true when more records exist beyond this page. Use it as your stop condition when iterating—do not rely on data.length.
​
url
string
The path of the list endpoint that produced this response.

​
Parameters

​
limit
integer
default:"10"
Number of records to return per page. Must be between 1 and 100.
​
starting_after
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.
​
ending_before
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/loc_9aZ4cR2pK1/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/loc_9aZ4cR2pK1/special_closings?limit=2&starting_after=scl_3Qm9vT7nB4" \
  -H "x-api-key: ch_org_live_5fK..."
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/loc_9aZ4cR2pK1/special_closings?limit=2&ending_before=scl_8Hk2wF6dJ0" \
  -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.
​
created_after
string
Only return records created strictly after this ISO 8601 timestamp.
​
created_before
string
Only return records created strictly before this ISO 8601 timestamp.
​
updated_after
string
Only return records updated strictly after this ISO 8601 timestamp.
​
updated_before
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/loc_9aZ4cR2pK1/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/loc_9aZ4cR2pK1/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.