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:
countis the total number of query results.
count_currentis the number of query results included in this results page.
is_limitedis false if this is the last results page, true otherwise.
next_urlis 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 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
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
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
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
sortquery 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.