Pagination

All list endpoints in Weave’s public API are paginated. Collections can grow arbitrarily large, so fetching a full collection in a single request is not supported.

How it works

Paginated list requests accept two optional fields: these are query parameters for GET endpoints and JSON body fields for POST endpoints.

  • page_size - The maximum number of results to return. If omitted or set to 0, the API uses a default page size (documented per endpoint). If you request more than the maximum allowed, the request is rejected with an error. Negative values are rejected with an error.
  • page_token - An opaque token identifying where to resume. Pass the next_page_token from a previous response to retrieve the next page.

Responses include:

  • The list of results for that page.
  • next_page_token - A token to pass as page_token in the next request. If this field is absent or empty, you have reached the end of the collection.
  • previous_page_token - Some endpoints optionally return this token, which can be passed as page_token to retrieve the previous page. Not all endpoints support this - check the individual endpoint documentation.

Iterating through pages

To iterate through all results, repeat requests with the next_page_token from each response until next_page_token is no longer returned.

GET /v1/things?page_size=50
→ { "things": [...], "next_page_token": "abc123" }

GET /v1/things?page_size=50&page_token=abc123
→ { "things": [...], "next_page_token": "def456" }

GET /v1/things?page_size=50&page_token=def456
→ { "things": [...] }
# no next_page_token = end of collection

Important notes

  • Page tokens are opaque strings - do not attempt to parse or construct them.
  • Page tokens will always be URL-safe
  • Page tokens may expire after a period of time. If a token has expired, restart pagination from the beginning.
  • All parameters other than page_token and page_size must remain the same across pages in a single pagination session. Changing other parameters while paginating may result in an error or inconsistent results.
  • The API may return fewer results than page_size on any given page, even before reaching the end of the collection. Do not use the size of returned collections to determine end of pagination - always rely on the presence or absence of next_page_token.