Pagination

Cursor-Based pagination explained, JSON:API Style.

Our API supports cursor-based pagination, inspired by the JSON:API pagination specification. This approach is efficient and scalable for large datasets.

Each paginated response contains a data array and links for navigating through pages.


πŸ“¦ Response Format

{
  "data": <...>,
  "links": {
    "self": "https://api.example.com/resources?cursor=abcdef",
    "next": "https://api.example.com/resources?cursor=ghijkl"
  }
}

πŸ”— links.self

URL for the current page. Safe to cache or re-fetch.

πŸ”— links.next

URL for the next page. If absent or null, you've reached the end.

🧭 cursor

A cursor is an opaque string provided by the server to mark a position in the dataset. You must use it exactly as returned. Do not attempt to decode or generate it manually.


πŸ” Authentication Required

Before making any paginated requests, make sure your client is authenticated properly.

➑️ See the Authentication section for details on required headers.


🟑 cURL

curl "https://api.example.com/resources" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret"

Then use the links.next URL:

curl "https://api.example.com/resources?page[cursor]=ghijkl" \
  -H "X-API-KEY: your-api-key" \
  -H "X-API-SECRET: your-api-secret"

βœ… Best Practices

  • Always use the links.next URL for pagination.

  • Never parse or construct cursors manually.

  • Stop paginating when links.next is missing or null.

  • Ensure authentication headers are included β€” see the Authentication section.

Last updated

Was this helpful?