Pagination

All list endpoints in the Diversity Sync API are paginated with cursor-based (keyset) pagination. You control the page size with limit and walk forward through the result set with starting_after, following the has_more flag until there's nothing left to fetch.

Every list response is the same uniform envelope: an object of "list", the url the list was requested from, a has_more boolean, and a data array of objects. By default a list returns 25 items; you can request between 1 and 100 with limit.

To page forward, pass the id of the last item you saw as starting_after — cursors are keyset-based, so there are no offsets or page numbers to track, and results stay stable even as items are added.

The list envelope

Every list endpoint returns the same shape, regardless of resource.

  • Name
    object
    Type
    string
    Description

    Always list for a paginated collection.

  • Name
    url
    Type
    string
    Description

    The path the list was requested from, for example /v1/staff.

  • Name
    has_more
    Type
    boolean
    Description

    Whether there are more items after this page. Keep paging while this is true.

  • Name
    data
    Type
    array
    Description

    The array of objects for this page, each carrying its own object discriminator.

Parameters

Pass these as query parameters on any list endpoint.

  • Name
    limit
    Type
    integer
    Description

    The number of items to return (1–100). Defaults to 25.

  • Name
    starting_after
    Type
    string
    Description

    A cursor for use in pagination. Set this to the id of the last item on the previous page to fetch the next page. For resources identified by a ref or name rather than a numeric id, pass that ref / name string instead. Omit it to start from the first page.

ending_before (backward pagination) is not yet supported. Lists can only be walked forward, from the start of the result set.

Request

GET
/v1/staff
curl -G https://api.diversitysync.com/v1/staff \
  -H "Authorization: Bearer {access_token}" \
  -d limit=25

Response

{
  "object": "list",
  "url": "/v1/staff",
  "has_more": true,
  "data": [
    {
      "object": "staff",
      "id": 482,
      "name": "Jordan Avery",
      "livemode": true
    },
    {
      "object": "staff",
      "id": 491,
      "name": "Riley Chen",
      "livemode": true
    }
  ]
}

Paging through every result

To collect a full result set, request the first page, then keep requesting while has_more is true, each time passing the id of the last item in data as starting_after. Stop as soon as has_more is false.

The next request reuses the previous response's last id as the cursor. Here the last item on the first page was 491, so the second request asks for everything after it.

  • Name
    starting_after
    Type
    string
    Description

    The id of the last item from the previous page (491 here).

Next page

GET
/v1/staff
curl -G https://api.diversitysync.com/v1/staff \
  -H "Authorization: Bearer {access_token}" \
  -d limit=25 \
  -d starting_after=491

Response

{
  "object": "list",
  "url": "/v1/staff",
  "has_more": false,
  "data": [
    {
      "object": "staff",
      "id": 503,
      "name": "Sam Okafor",
      "livemode": true
    }
  ]
}

When has_more is false, you've reached the end of the result set and the last page has been delivered.

Was this page helpful?