Pagination

Every Spot Thought REST collection follows the same offset/limit contract. Each list response includes a total count, the effective limit and offset, and the array of rendered resources. Requests accept a nested pagination object in the query string so you can jump to any slice of the dataset.

Request parameters

Use the following query parameters to page through results:

Name
pagination[offset]
Type
number
Description
The index of the first item you want to receive. Defaults to 0.
Name
pagination[limit]
Type
number
Description
The maximum number of items to return. Defaults to 100 and cannot exceed 500.

If you omit the pagination object entirely you will get the default window (offset=0, limit=100). Setting limit above the maximum is automatically clamped, and offset values below zero are rejected by the schema.

Example request

The example below fetches 25 participants starting after the first 50 matching records. The same pattern works for every other collection (screeners, publications, messages, etc.).

List participants (page 3)

curl -G https://api.spot-thought.com/participants \
  -H "Authorization: Bearer {token}" \
  --data-urlencode "pagination[offset]=50" \
  --data-urlencode "pagination[limit]=25"

Response shape

Regardless of the resource, a paginated response has the following structure:

Name
total
Type
number
Description
Total number of matching items in the collection.
Name
limit
Type
number
Description
Effective page size used for the response (after clamping).
Name
offset
Type
number
Description
Index of the first item returned in items.
Name
items
Type
array
Description
Array of rendered resources for the current slice.

Paginated response

{
  "_type": "PaginatedParticipant",
  "total": 248,
  "limit": 25,
  "offset": 50,
  "items": [
    {
      "_type": "Participant",
      "id": "par_6Lq8jCCk1",
      "externalUid": "crm_9832",
      "email": "avery@example.com",
      "name": {
        "first": "Avery",
        "last": "Jones"
      },
      "createdAt": "2024-10-05T19:42:11.000Z",
      "updatedAt": "2024-10-05T19:42:11.000Z"
    }
    // ...
  ]
}