API ReferenceRoutes
List routes
Fetch a list of routes based on the provided query. The query may include a limit, sort key, timestamp bounds, and whether to include archived routes. The response will include a list of routes and a cursor to fetch the next page of results. Subsequent requests should include the cursor only and no list query arguments (which are encoded in the cursor).
Authorization
bearerAuth AuthorizationBearer <token>
Access token from /authenticate
In: header
Query Parameters
query.limit?integer
Maximum number of routes to return. Must be less than or equal to 200.
Defaults to 20.
Format
int32Range
value <= 200query.sortKey?string
Sort key for the returned routes. This determines the ordering of returned routes.
Format
enumValue in
- "UNKNOWN"
- "CREATED_AT"
- "UPDATED_AT"
query.timestampStart?string
Lower bound timestamp for the returned routes. This bound is applied to either the route created time or updated time, depending on the sort key.
Format
date-timequery.timestampEnd?string
Upper bound timestamp for the returned routes. This bound is applied to either the route created time or updated time, depending on the sort key.
Format
date-timequery.includeArchived?boolean
Whether to include archived routes in the results.
cursor?string
Must be empty on initial request, must be set on subsequent.
Response Body
application/json
application/json
curl -X GET "https://example.com/routes"{ "routes": [ { "id": "rte-123e4567-e89b-12d3-a456-426614174000", "name": "Morning route", "driver": { "id": "drv-123e4567-e89b-12d3-a456-426614174000", "firstName": "John", "lastName": "Doe", "phone": "+14265551000", "status": "ACTIVE" }, "start": { "address": { "address1": "123 Main St", "address2": "Apt 3B", "city": "New York", "provinceCode": "NY", "countryCode": "US", "zip": "10001" }, "tasks": [ { "id": "tsk-123e4567-e89b-12d3-a456-426614174000", "title": "Delivery checklist", "type": "TEXT_INPUT", "items": [], "input": { "value": "020123456789", "updatedAt": "2019-08-24T14:15:22Z", "inputMethod": "SCANNED" }, "requiredToMarkStopAsDelivered": true, "requiredToMarkStopAsAttempted": true } ], "status": "STARTED", "updatedStart": "2019-08-24T14:15:22Z", "scheduledStart": "2019-08-24T14:15:22Z", "photos": [ { "id": "att-123e4567-e89b-12d3-a456-426614174000", "createdAt": "2019-08-24T14:15:22Z", "url": "https://example.com/stop-attachment/attachment-2025-06-03-1" } ] }, "end": { "address": { "address1": "123 Main St", "address2": "Apt 3B", "city": "New York", "provinceCode": "NY", "countryCode": "US", "zip": "10001" }, "tasks": [ { "id": "tsk-123e4567-e89b-12d3-a456-426614174000", "title": "Delivery checklist", "type": "TEXT_INPUT", "items": [], "input": { "value": "020123456789", "updatedAt": "2019-08-24T14:15:22Z", "inputMethod": "SCANNED" }, "requiredToMarkStopAsDelivered": true, "requiredToMarkStopAsAttempted": true } ], "plannedArrival": "2019-08-24T14:15:22Z", "distanceMeters": 1234.56, "updatedArrival": "2019-08-24T14:15:22Z", "status": "COMPLETED", "photos": [ { "id": "att-123e4567-e89b-12d3-a456-426614174000", "createdAt": "2019-08-24T14:15:22Z", "url": "https://example.com/stop-attachment/attachment-2025-06-03-1" } ] }, "stops": [ { "id": "rst-123e4567-e89b-12d3-a456-426614174000", "type": "DELIVERY", "deliveryStatus": "ATTEMPTED_DELIVERY", "breakStatus": "COMPLETED", "updatedAt": "2019-08-24T14:15:22Z", "duration": "string", "plannedArrival": "2019-08-24T14:15:22Z", "note": "Leave at door.", "address": { "address1": "123 Main St", "address2": "Apt 3B", "city": "New York", "provinceCode": "NY", "countryCode": "US", "zip": "10001" }, "contact": { "firstName": "John", "lastName": "Doe", "company": "Roundtrip Systems Inc", "phone": "+14265551000", "email": "john.doe@roundtrip.ai" }, "plannedCoordinates": { "latitude": 0.1, "longitude": 0.1 }, "items": [ { "name": "Bananas", "quantity": 5, "grams": 500, "sku": "BANANA-001" } ], "source": "IMPORTED_STOP", "shopifyOrderId": "6229749334323", "savedStopId": "sst-123e4567-e89b-12d3-a456-426614174000", "deliveredCoordinates": { "latitude": 0.1, "longitude": 0.1 }, "proofOfDeliveryNote": "Left at door.", "proofOfDeliveryPhotos": [ { "id": "att-123e4567-e89b-12d3-a456-426614174000", "createdAt": "2019-08-24T14:15:22Z", "url": "https://example.com/stop-attachment/attachment-2025-06-03-1" } ], "proofOfDeliverySignatures": [ { "id": "att-123e4567-e89b-12d3-a456-426614174000", "createdAt": "2019-08-24T14:15:22Z", "url": "https://example.com/stop-attachment/attachment-2025-06-03-1" } ], "tasks": [ { "id": "tsk-123e4567-e89b-12d3-a456-426614174000", "title": "Delivery checklist", "type": "TEXT_INPUT", "items": [], "input": { "value": "020123456789", "updatedAt": "2019-08-24T14:15:22Z", "inputMethod": "SCANNED" }, "requiredToMarkStopAsDelivered": true, "requiredToMarkStopAsAttempted": true } ], "priority": 8, "importedStopId": "ist-123e4567-e89b-12d3-a456-426614174000", "orderName": "#1234", "distanceMeters": 123.45, "updatedArrival": "2019-08-24T14:15:22Z", "timeWindows": [ { "start": { "hours": 13, "minutes": 37, "seconds": 16 }, "end": { "hours": 13, "minutes": 37, "seconds": 16 } } ], "deliveryDate": { "year": 2019, "month": 11, "day": 15 }, "attributes": [ { "key": "delivery_date", "value": "2025-12-16" } ], "clientStopId": "test-order-1234", "tags": [ "foo", "bar" ], "attemptedReason": "NOT_AVAILABLE", "attemptedNote": "Customer did not answer the door.", "customerRating": { "rating": 5, "comment": "Excellent delivery", "createdAt": "2019-08-24T14:15:22Z" }, "customSignatureDisclosure": "I acknowledge that I have received this delivery.", "shopifyOrder": { "orderNote": "Customer has paid.", "customerNote": "Leave at door." }, "proofOfDeliveryBarcodes": [ { "value": "string", "createdAt": "2019-08-24T14:15:22Z" } ], "proofOfDeliveryBarcodeIssues": [ { "reason": "ITEM_MISSING", "note": "Item was not packed.", "createdAt": "2019-08-24T14:15:22Z" } ] } ], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "archivedAt": "2019-08-24T14:15:22Z", "scheduledFor": "2019-08-24T14:15:22Z", "totalDistanceMeters": 2387.2, "totalItemQuantity": 50, "totalItemGrams": "6000", "optimized": true, "dispatchedUntil": "2019-08-24T14:15:22Z", "note": "Fragile items.", "tags": [ "foo", "bar" ], "defaultStopDuration": "300s", "maxDuration": "28800s", "maxStops": 50, "maxItemCount": 200, "maxKilograms": 500, "avoidTolls": true, "avoidUTurns": true, "speedFactor": 0.8 } ], "nextCursor": "string"}{ "code": 0, "message": "string", "details": [ { "@type": "string" } ]}