---
title: "List routes for a specific plan"
method: GET
path: "/hub/plan/routes"
tags: ["Routes"]
---

# List routes for a specific plan

`GET /hub/plan/routes`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/hub/plan/routes`
- Auth: HTTP bearer

Retrieve routes for a specific plan.

 <b>Rate limit:</b> 10 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select **Read Routes** under the Driver Workflow category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
 

 **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

## Query parameters

- `planId` string, required
- `routeIds` string
- `startTime` string, date-time
- `endTime` string, date-time
- `after` string
- `limit` integer

## Response `200`

OK response.

- HubPlanRoutesListHubPlanRoutesResponseBody
  - `data` RouteObjectResponseBody[], required: Route data
    - `cost` number, double, required: The cost of the route
    - `createdAt` string, date-time, required: The timestamp (in UTC) when the route was created
    - `dispatchRouteId` string: The dispatch route identifier
    - `distanceMeters` integer, required: The total distance of the route in meters
    - `driver` RouteDriverObjectResponseBody: A driver object. This object is only returned if the route is assigned to a driver.
      - `id` string, required: ID of the driver
      - `name` string: Name of the driver
    - `durationSeconds` integer, required: The total duration of the route in seconds
    - `hubId` string, required: The ID of the hub this route belongs to
    - `id` string, required: The Samsara-generated unique identifier (UUID) for the route
    - `isEdited` boolean, required: Whether the route has been edited
    - `isPinned` boolean, required: Whether the route is pinned
    - `name` string, required: The name of the route
    - `orgLocationTimezone` string, required: The organization location timezone calculated from hub
    - `planId` string, required: The ID of the plan this route belongs to
    - `quantities` QuantityObjectResponseBody[]: List of quantity information for the route
      - `capacityId` string, required: The capacity identifier
      - `quantity` number, double, required: The quantity value
    - `scheduledRouteEndTime` string, date-time, required: The scheduled end time of the route calculated from last stop
    - `scheduledRouteStartTime` string, date-time, required: The scheduled start time of the route calculated from first stop
    - `stops` RouteStopObjectResponseBody[], required: List of stops on the route
      - `hubLocationId` string: The hub location identifier from dispatch
      - `id` string, required: The Samsara-generated unique identifier (UUID) for the stop
      - `name` string, required: The name of the stop
      - `notes` string: Additional notes for the stop
      - `orders` OrderTaskObjectResponseBody[]: List of order tasks associated with this stop
        - `customProperties` OrderTaskCustomPropertyObjectResponseBody[]: List of custom properties for the order
          - `id` string, required: The custom property identifier
          - `name` string, required: The custom property name
          - `value` string, required: The custom property value
        - `customerLocationId` string: The external ID of the location associated with this order
        - `id` string, required: The order identifier
        - `quantities` QuantityObjectResponseBody[]: List of quantity information for the order
          - `capacityId` string, required: The capacity identifier
          - `quantity` number, double, required: The quantity value
        - `requiredSkills` OrderTaskSkillObjectResponseBody[]: List of required skills for the order
          - `id` string, required: The skill identifier
          - `name` string, required: The skill name
        - `serviceWindow` string: The service window time range
        - `type` string, required: The task type (pickup or delivery)
      - `scheduledArrivalTime` string, date-time, required: The scheduled arrival time at the stop
      - `scheduledDepartureTime` string, date-time, required: The scheduled departure time from the stop
      - `singleUseLocation` SingleUseLocationObjectResponseBody: Single use location for route stops
        - `address` string, required: The full address string
        - `latitude` number, double, required: Latitude coordinate
        - `longitude` number, double, required: Longitude coordinate
    - `type` string, required: The type of route
    - `updatedAt` string, date-time, required: The timestamp (in UTC) when the route was last updated
    - `vehicle` RouteVehicleObjectResponseBody: A vehicle object. This object is only returned if the route is assigned to a vehicle.
      - `id` string: ID of the vehicle
      - `name` string: Name of the vehicle
  - `pagination` ListHubPlanRoutesResponsePaginationResponseBody, required: Pagination information
    - `endCursor` string: Cursor for the last item in the page
    - `hasNextPage` boolean, required: Whether there are more pages available

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)