Pagination

Many Core API endpoints return paginated results when you make a GET request to list the resources. For example, the List conversations and the List contacts endpoints return paginated results. Returning paginated results improves performance but requires that you implement the pagination strategy described in this topic when fetching these resources.

An endpoint that returns paginated results will include a page_token query parameter in the request and a _pagination object in the response. Refer to the Core API Reference to determine whether specific endpoints are paginated.

How to handle paginated results

Complete the following steps to iterate through paginated results:

1. On the first API call, include a limit query string parameter indicating how many results to display per page (max is 100). For example:
   HTTP

   GET https://api2.frontapp.com/contacts?limit=25

2. The response will include a _pagination object that will look like:
   JSON

   "_pagination": {
     "next": "https://yourDomain.api.frontapp.com/contacts?limit=25&page_token=2d018a5809eb90d349bc08c52cb1f4980dace06bd942acb6ed6849ff28c81a6e128e533ca8bf433d1365a786fd0fc660802266eadf8b92696d885a21076a8604"
   }

3. Extract the next value within the _pagination object. In the previous example, the URL of the next page of results would be https://yourDomain.api.frontapp.com/contacts?limit=25&page_token=2d018a5809eb90d349bc08c52cb1f4980dace06bd942acb6ed6849ff28c81a6e128e533ca8bf433d1365a786fd0fc660802266eadf8b92696d885a21076a8604.

   📘

   Always use the next value to determine if there are additional results.

   The API may sometimes return fewer results than the requested limit, especially if resources have been deleted. This does not indicate that there are no more results.

   Do not rely on result counts—always use the next value to paginate reliably.

4. Make your next API request to the URL you extracted in the previous step. You do not need to include another limit parameter as the link you extracted will already include the limit you specified in the initial request. For example:
   HTTP

   GET https://yourDomain.api.frontapp.com/contacts?limit=25&page_token=2d018a5809eb90d349bc08c52cb1f4980dace06bd942acb6ed6849ff28c81a6e128e533ca8bf433d1365a786fd0fc660802266eadf8b92696d885a21076a8604

5. Repeat this process until the next value returns null. This means you've reached the end of the results. For example:
   JSON

   "_pagination": {
     "next": null
   }

Tips

• Include the limit query string parameter in the initial request if you want to specify how many results should be returned per page. If left unspecified, the API returns 50 results per page. The maximum limit you can specify is 100 results per page. For example, the following request specifies 100 results be returned per page:
  HTTP

  GET https://api2.frontapp.com/contacts?limit=100&page_token=2d018a5809eb90d349bc08c52cb1f4985dc941e2a017b2256265872eeef423f9e2e0cf3ba5dad753313f3d8e48bedbf0f6ad09d808339c61a1369073bee4accb

• The URL value of the current page of results can be obtained from the self parameter in the _links object. You can store this value if you want to return to previous results from the next page.
  JSON

  "_links" {
    "self": "https://yourDomain.api.frontapp.com/contacts?page_token=2d018a5809eb90d349bc08c52cb1f4985758d02b20a11cdb57c7a3f4c8ded2affb50d31f307017ef1d6487c80c1f3eec36221ee3c1b2216647a59d45394471a0"
  }