Pagination
Some endpoints return a lot of data. They return it a page at a time: you ask for a page, and the response tells you how to ask for the next one.
Which endpoints are paginated
| Endpoint | Description | Page size |
|---|---|---|
/safety-events | Safety events in a date range | 50 by default, at most 500 |
/accidents | Accidents and minor collisions in a date range | 50 by default, at most 500 |
/trips | Trips in a date range | 50 by default, at most 500 |
/coachings/messages | Coaching messages in a date range | 50 by default, at most 100 |
/reports/safety-scores/vehicles | Vehicle safety scores | 10 by default, at most 100 (see below) |
/reports/safety-scores/drivers | Driver safety scores | 10 by default, at most 100 (see below) |
/reports/safety-scores/vehicles and /reports/safety-scores/drivers page differently from the others: it takes page (starting at 1) and pageSize instead of limit and cursor, and next stays null. Use total in the response to know how many pages there are. See Safety Scores.
All other endpoints, including /connections, /drivers and /vehicles, are not paginated: they return everything at once and ignore limit and cursor.
Large fleets: drivers and vehicles
/drivers and /vehicles return every record of the connection in one response, so the size of the response grows with the fleet. Measured on the production API in October 2026:
| Request | Records | Size | Time |
|---|---|---|---|
GET /drivers | 1,235 drivers | 0.3 MB | about 3 seconds |
GET /vehicles | 2,211 vehicles | 1.0 MB | about 5 seconds |
GET /vehicles | 3,775 vehicles | 1.6 MB | about 16 seconds |
For fleets of this size the lists work, but a vehicle list of several thousand records is slow. Fetch the lists once, keep them, and refresh them a few times a day instead of before every request, and give the request a generous timeout (60 seconds or more for the vehicle list). To look at one record, use GET /vehicles/{vehicleId} or GET /drivers/{driverId}. Pagination for these two endpoints is not available today.
Query parameters
limit: the number of items per page. The default and the maximum are in the table above. A value outside the allowed range answers400.cursor: a token that marks where the next page starts. Use thenextvalue of the previous response; do not build or change a cursor yourself.
Response fields
data: the items of this page.next: when more items follow, the cursor of the next page. When it isnull, this was the last page.
Example workflow
- Send the first request without a
cursor, for exampleGET /safety-events?from=2026-10-01&to=2026-10-12&limit=100. - Read
nextin the response. If it holds a value, more data is available. - Send the same request again with
cursor=<next>. - Repeat until
nextisnull.
Keep the other parameters (the date range and the filters) the same on every request of one run. The example response below is shortened to one item.
{
"status": 200,
"message": null,
"data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "Harsh Braking" } ],
"next": "eyJvZmZzZXQiOjEwMH0"
}Best practices
- Pick a
limitthat suits your client: a larger page means fewer requests, a smaller one a faster first response. - Keep the last
nextvalue in your logs, so an interrupted run can continue where it stopped. - Read pages one after the other. A cursor belongs to the request it came from.
Updated 1 day ago