Pagination

How the API pages its lists, by cursor for searches and by page number for plain lists.

You choose how many items each page holds: 25 by default, up to 100, set with limit (cursor) or page_size (page number). The exceptions are listed below.

One rule decides how a list is paged:

Searches (POST .../query, except the companies search) and credit usage page by cursor.
Plain lists (GET endpoints that return a list, such as signal templates, signal setups or lists) page by page number.

Two plain lists differ: request status takes page_size from 1 to 500 and defaults to 500, and list signal runs is not paged at all: it returns every run in one response.

The companies search (POST /v3/companies/query, Search companies) is not paged: it returns the first limit matches (default 20, up to 50), sorted by name from A to Z, and no cursor. If you get exactly limit results, refine name or domain.

Cursor pagination

A cursor moves forward through a search, one page at a time. It stays correct while new items arrive: nothing is skipped or repeated.

Parameters

Parameter	Type	Default	Description
cursor	string	none	The `meta.cursor.next` of the previous response. Omit it for the first page.
limit	integer	25	Number of items per page, from 1 to 100.

cursor and limit go in the JSON body of a search, and in the query string of credit usage.

Response shape

{
  "data": [],
  "meta": {
    "cursor": {
      "next": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTEyVDA5OjE1OjAwLjAwMFoiLCJpZCI6MTIwMzg0fQ.k3Jx0w",
      "has_more": true
    }
  }
}

Field	Description
meta.cursor.next	Send it back as `cursor` to get the next page. `null` on the last page.
meta.cursor.has_more	`true` when more items exist after this page, `false` on the last page.

Rules

Treat the cursor as an opaque value. Do not build it, read it or change it.
A cursor is bound to the filters, and to the sort when the search has one, it was issued for. Reused with other filters or another sort, it is refused with 422.
A cursor only works on the endpoint and the workspace that issued it. A cursor issued on a direct route is refused on its partner route, and the other way round. Any other cursor, and an empty cursor, is refused with 422.
limit may change from one page to the next.
A limit outside 1 to 100 is refused with 422.
Keep going until meta.cursor.has_more is false.

Example

The first page, then the next one:

curl -X POST "https://api.getsillage.com/api/v3/contents/query" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":25}'

Send meta.cursor.next of the response back as cursor:

curl -X POST "https://api.getsillage.com/api/v3/contents/query" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":25,"cursor":"eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTEyVDA5OjE1OjAwLjAwMFoiLCJpZCI6MTIwMzg0fQ.k3Jx0w"}'

Page-number pagination

A plain list is read one numbered page at a time.

Parameters

Parameter	Type	Default	Description
page	integer	1	Page number, starting at 1.
page_size	integer	25	Number of items per page, from 1 to 100.

Response shape

{
  "data": [],
  "meta": {
    "pagination": {
      "page": 2,
      "page_size": 25,
      "page_count": 4,
      "total": 87
    }
  }
}

Page-numbered responses also carry these headers:

Header	Description
X-Total-Count	Total number of items.
X-Page	Current page number.
X-Page-Size	Current page size.
X-Page-Count	Total number of pages.

When meta.pagination.page equals meta.pagination.page_count, there are no more pages.

Pagination

On this page