​
Using pagination in the REST API

​
About pagination

When a response from the REST API would include many results, Buildr will paginate the results and return a subset of the results. For example, GET /api/2023-01/opportunities will only return 100 opportunities from the user’s account even though the account may contain over 100 opportunities. This makes the response easier to handle for servers and for people.

You can use the link header from the response to request additional pages of data. If an endpoint supports the per_page query parameter, you can control how many results are returned on a page.

This article demonstrates how to request additional pages of results for paginated responses, how to change the number of results returned on each page, and how to write a script to fetch multiple pages of results.

When a response is paginated, the response headers will include a link header. If the endpoint does not support pagination, or if all results fit on a single page, the link header will be omitted.

The link header contains URLs that you can use to fetch additional pages of results. For example, the previous, next, first, and last page of results.

To see the response headers for a particular endpoint, you can use curl to make requests. To see the response headers if you are using curl pass the —include flag with your request. For example:

curl --include --request GET \
--url "https://api.buildr.com/api/2023-01/opportunities

If the response is paginated, the link header will look something like this:

link: <https://api.buildr.com/api/2023-01/opportunities?page=2>; rel="prev", <https://api.buildr.com/api/2023-01/opportunities?page=4>; rel="next", <https://api.buildr.com/api/2023-01/opportunities?page=515>; rel="last", <https://api.buildr.com/api/2023-01/opportunities?page=1>; rel="first"

The link header provides the URL for the previous, next, first, and last page of results:

The URL for the previous page is followed by rel=“prev”. The URL for the next page is followed by rel=“next”. The URL for the last page is followed by rel=“last”. The URL for the first page is followed by rel=“first”. In some cases, only a subset of these links are available. For example, the link to the previous page won’t be included if you are on the first page of results, and the link to the last page won’t be included if it can’t be calculated.

You can use the URLs from the link header to request another page of results. For example, to request the last page of results based on the previous example:

curl --include --request GET \
--url "https://api.buildr.com/api/2023-01/opportunities?page=515"

The URLs in the link header use query parameters to indicate which page of results to return. You can use the URLs in the link header to fetch additional pages of results.

​
Changing the number of items per page

If an endpoint supports the per_page query parameter, then you can control how many results are returned on a page

For example, this request uses the per_page query parameter to return two items per page:

curl --include --request GET \
--url "https://api.buildr.com/api/2023-01/opportunities?per_page=2"

The per_page parameter will automatically be included in the link header. For example:

link: <https://api.buildr.com/api/2023-01/opportunities?per_page=2&page=2>; rel="next", <https://api.buildr.com/api/2023-01/opportunities?per_page=2&page=7715>; rel="last"
Rate limitingWebhooks