Pagination (Cursor)

We're starting to adopt a cursor-based approach to pagination for certain list resources.

📘
This currently only applies when listing Contacts.

Example Initial Request

$ curl https://api.intercom.io/contacts?per_page=5 \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json'

Initial Request

You can initially specify how many items per_page you want to fetch.

Parameter	Type	Description
per_page	Integer	The number of items returned in a single response. Default is 50. Max is 150.

Example Initial Pages Object

{
  "pages": {
    "type": "pages",
    "next": {
      "page": 4,
      "starting_after": "1HaSB+xrOyyMXAkS/c1RteCL7BzOzTvYjmjakgTergIH31eoe2v4/sbLsJWP\nIncfQLD3ouPkZlCwJ86F\n"
    },
    "page": 3,
    "per_page": 5,
    "total_pages": 10
   }
}

Response

In order to iterate through pages, you must parse the query response. A query with multiple response pages will include a next key in the pages object. When a next value is provided, the starting_after value must be sent back in a new request in order to iterate to the next page.

Parameter	Type	Description
starting_after	String	The cursor used for pagination in order to fetch the next page of results.

🚧
Paginating through all results
This method of pagination is used to iterate through a result set until all results have been fetched, not to directly go to page X of the results. This is not possible.

Example Subsequent Requests

$ curl https://api.intercom.io/contacts?starting_after="1HaSB+xrOyyMXAkS/c1RteCL7BzOzTvYjmjakgTergIH31eoe2v4/sbLsJWP\nIncfQLD3ouPkZlCwJ86F\n" \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json'

📘

Initial Request

Response

🚧Paginating through all results

🚧
Paginating through all results