Custom relative URI pagination method


Each page is denoted by the ID of the last object it holds, rather than its page. For example, if a 'page' returns 10 customers, then the ID of the last customer will be passed in the URL to get the next page.

Custom relative URI options


Link parameter path

Enter the dot notation path for the data element in your response which contains the maximum number of items that the API should return in a single page of a paginated response. Commonly (though not necessarily), this would be a path to a limit field.

Last ID parameter name

Enter the name of the query parameter to be passed into the URL to tell the receiving system the last record we received (so the receiving system knows where to start for the next page of data to return). A commonly used name is: last_id .


Enter the number of items to be returned per page. For example: 10.

ID key

Enter the unique identifier key for each item in your data. For example, if the endpoint is pulling a list of users, this might be: user_id.


Suppose we set the following options:


Link parameter path


Last ID parameter name




ID key


The following URL will be generated to get the first page:


Notice our link parameter path (limit) and the actual limit value (10) at the end of the request. Our first page would look something like the example below:

  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Charlie"},
    {"id": 4, "name": "Lyn"},
    {"id": 5, "name": "John"},
    {"id": 6, "name": "Gordon"},
    {"id": 7, "name": "Izzy"},
    {"id": 8, "name": "Mike"},
    {"id": 9, "name": "Ralph"},
    {"id": 10, "name": "Rex"}

When pagination runs, it will look for the last id key in the payload, and use that as the starting point for the next request. So the request for page 2 will be:


Notice our link parameter path (limit) and the actual limit value (10) at the end of the request, followed by our Last ID parameter name (starting_after) set to the last id in the response.

A sample response for this request is below:

  "data": [
    {"id": 11, "name": "Josh"},
    {"id": 12, "name": "Adam"},
    {"id": 13, "name": "Tom"},
    {"id": 14, "name": "Aaron"},
    {"id": 15, "name": "Conor"},
    {"id": 16, "name": "Luke"},
    {"id": 17, "name": "Andrew"},
    {"id": 18, "name": "Nathan"},
    {"id": 19, "name": "Lee"},
    {"id": 20, "name": "Dean"}

When does pagination stop?

Pagination continues until the the number of items in the payload is less than the limit, or the page returns an error code.

Last updated