Pagination

The REST API limits GET queries to 100 results by default. It is possible to increase this limit using the limit query parameter. However, if it is necessary to fetch more than 100, it is recommended to use the API's pagination features instead to prevent load spike and mitigate the risk of request timeouts.

The result envelope included in the response to a GET query by default contains a number of pagination-related properties:

• count is the total number of query results.
• count_current is the number of query results included in this results page.
• is_limited is false if this is the last results page, true otherwise.
• next_url is an aid for ID-based pagination. This might not always be available depending on query parameters.

Pagination can be achieved using an ID-based method or a limit/skip-based method.

ID-based pagination

ID-based pagination makes use of the fact that IDs are chronological. Using the after_id (for a chronological query) or before_id (for a reverse chronological query, the default) query parameter, the next set of results can be fetched until there are none left. This kind of pagination is recommended when fetching all results of a (reverse) chronological query with a high result count.

ID-based pagination can be done manually by taking the ID of the last result and using that as after_id/before_id for the next query, repeating this process until is_limited is false. To simplify this process for applications, the API response includes a next_url with the correct after_id/before_id already set. The easiest way to implement ID-based pagination is therefore to check if there is a next_url and keep requesting the next_url until the next_url is null.

Limit/skip-based pagination

Starting with Brain version 2.6, the skip query parameter can be used to skip over a given number of results. Along with the limit query parameter this can be used as an alternative pagination method, for example: fetch the first 50 results, then skip 50 to get the next 50 results, then skip 100 to get the next 50 results, et cetera. This kind of pagination is recommended in the following situations:

• The goal is to fetch a specific range of results (e.g. in a graphical view with pagination), because the pages do not necessarily have to be fetched in order like with ID-based pagination.
• The query is not ordered by ID, i.e. uses the sort query parameter on a property other than the ID field.

It is not recommended for iterating through all results of a query sequentially because there is a risk of duplicate or missing records if records are deleted during the operation.