Most Burq API endpoints that return a list of objects do so with pagination. We use cursor-based pagination across the board to avoid shift in page boundaries from concurrent traffic.
When calling these APIs to retrieve records, you'd normally start without any cursor parameter. After you receive the first page of records, take the id value of the last record, and set it to the cursor parameter for your next request to load the subsequent page of records. When setting the cursor parameter, you can choose between starting_after and ending_before. Only one of the two cursor parameters can be set at a time. When you set the starting_after parameter, records created before the cursor object are returned. Conversely, records created after the cursor are returned when ending_before is set.
The list of records in the response are sorted in descending order based on the date of their creation. If the date of creation is the same between two records, their IDs are used as the secondary tie-breaker. This ensures deterministic order in which records are returned.
In most list APIs, the response includes a data field that contains an array of the records, and a boolean field, has_more, which indicates whether there are more records beyond the current page. To understand the behavior of has_more, imagine a pagination control in the UI made of two buttons - "previous" and "next". The has_more field always tells you whether you should display the "next" button, regardless of whether the user clicked "previous" or "next" (aka. regardless of whether you are using starting_after or ending_before as the cursor). This may be a different behavior from some of the other common cursor-based pagination implementations. However, after dogfooding a few different implementations, we found this particular behavior to be the simplest option to work with. This does mean, however, that when you are programmatically calling the "previous" pages, you will need to handle empty pages and not rely on has_more.
To learn more about pagination, please check out the documentation for list-deliveries API and try hitting it with different parameters.