Pagination
The Fleetio API returns data set in pages, instead of all at once. This common API pattern allows us to efficiently return query results without putting unnecessary strain on our resources.
We have started a transition away from page count based pagination, and towards cursor pagination. Cursor pagination will perform much more consistently for all users and improve performance for API users. New index endpoints will support only cursor pagination.
The new endpoints supporting cursor pagination only exist in API versions starting with 2024-01-01. They can be identified by the response, which returns an object with pagination data, applied filters and sorts, and the array of records in the records attribute.
New endpoints with cursor based pagination
Index endpoints will return 50 records by default for most endpoints. This can be customized by passing in the query parameter per_page.To visit the subsequent page, copy the next_cursor attribute in the response into the start_cursor url parameter. The subsequent page response will confirm this by indicating the current_cursor. Pagination headers are no longer returned. See the table below for query parameters and response parameters.
Query parameters
| Query Parameter | Description |
|---|---|
start_cursor | The cursor at which to return the subsequent records, respecting the sort order and filters. Leave blank for first page. |
per_page | The number of records to return in each response. Maximum supported is 100. |
Response attributes
| Response Attribute | Description |
|---|---|
current_cursor | The cursor corresponding to the current page of records. |
next_cursor | The cursor corresponding to the next page of records. Use the value for this attribute in the query parameter next_cursor to return the next page of records. |
per_page | The per_page limit applied to the request, or the default per page, usually 50. |
estimated_remaining_count | An approximate number of remaining records up to a maximum count, usually 500. If there are more than 500 records left, you will not see less than 500 in this field until there are fewer than 500 records after your current_cursor respecting the filters and sorts applied. |
filtered_by | An array of the filters applied to the request. |
sorted_by | An array of the sorts applied to the request. |
records | The array of records meeting the filtered_by criteria, ordered by the sorted_by criteria, starting with the current_cursor, and limited to the lesser of the remaining records or per_page. |
Older endpoints with page number based pagination
In Fleetio, all index actions return paginated responses. Each page will contain up to 100 items—this number may change though, so don't code yourself into a wall by hardcoding 100 as the expected page size. Fleetio returns four response headers along with the result set to help you work with the paginated data.
| Header | Description |
|---|---|
X-Pagination-Limit | The per page limit. Set to 100 but subject to change at any time. |
X-Pagination-Current-Page | The current page. Defaults to 1. |
X-Pagination-Total-Pages | The total number of pages in the result set. Use this along with X-Pagination-Current-Page to determine if there are any remaining pages/records to be retrieved. |
X-Pagination-Total-Count | The total number of records in the result set (across all pages). |
To retrieve data for a specific page, specify the page query parameter as in the example below.
# Get the second page of results for the vehicles index action.
curl \
--header "Authorization: Token YOUR_API_KEY" \
--header "Account-Token: YOUR_ACCOUNT_TOKEN" \
"https://secure.fleetio.com/api/v1/vehicles?page=2"
Pages start at 1. If the request does not include a page parameter, the server will return the first page of results. If the page parameter is less than 1, it will also return the first page of results. If the page parameter is greater than Pagination-Total-Pages, it will return an empty result set.
You can also set the number of items per page by specifying the per query parameter. The default is 100, but you can set it to any value between 1 and 100.
# Get the first page of results for the vehicles index action, set to 50 items.
curl \
--header "Authorization: Token YOUR_API_KEY" \
--header "Account-Token: YOUR_ACCOUNT_TOKEN" \
"https://secure.fleetio.com/api/v1/vehicles?per=50"