--- title: "Get Routes" method: GET path: "/orders/routes/" tags: ["Orders"] --- # Get Routes `GET /orders/routes/` ## Request - Base URL: `https://v3.api.hypertrack.com` - URL: `https://v3.api.hypertrack.com/orders/routes/` - Auth: one of: - HTTP basic - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieve routes based on the filter parameters provided Unplanned orders may include planning_failure_reason, a customer-facing explanation of why automated planning could not assign the order. ## Query parameters - `completed_at_date` string, nullable - `completed_at_from` string, nullable - `completed_at_to` string, nullable - `created_at_date` string, nullable - `created_at_from` string, nullable - `created_at_to` string, nullable - `worker_handle` string, nullable - `driver_handle` string, nullable - `ops_group_handle` string, nullable - `plan_mode` 'on_demand' | 'scheduled' | 'manual' | 'null', nullable - `planned_at_date` string, nullable - `planned_at_from` string, nullable - `planned_at_to` string, nullable - `region_filter` string, nullable - `route_metadata_filter` string, nullable - `sort_direction` 'asc' | 'desc' | 'null', nullable - `start_by_date` string, nullable - `start_by_from` string, nullable - `start_by_to` string, nullable - `started_at_date` string, nullable - `started_at_from` string, nullable - `started_at_to` string, nullable - `scheduled_start_at_from` string, nullable - `scheduled_start_at_to` string, nullable - `status` string, nullable - `track_mode` 'full_shift' | 'on_shift' | 'pre_shift' | 'null', nullable - `pagination_token` string, nullable - `search_term` string, nullable - `limit` integer, nullable - `device_switch_mode` unknown - `plan_id` string, nullable - `device_id` string, nullable - `device_metadata_filter` string, nullable - `route_handle` string, nullable ## Response `200` Successful response - GetRoutesResponse - `routes` RouteList[], required - `route_handle` string, required: Unique identifier for the route - `status` 'planned' | 'assigned' | 'tracking' | 'completed' | 'summarizing', required: Current state of route - `version` integer, required: Value indicating the latest updated state of the route - `created_at` string, required: Timestamp at which the route was created - `embed_url` string, required: Embeddable link that renders the route profile view - `orders` RouteListOrder[], required: List of orders to be fulfilled in the route - `order_handle` string, required: Unique customer provided identifier for an order - `status` 'completed' | 'cancelled' | 'disabled' | 'ongoing' | 'unplanned' | 'assigned' | 'planned' | 'dispatched' | 'summarizing', required: Current state of the order - `planning_failure_reason` string, nullable: Reason explaining why automated planning left the order unplanned. Present only when a planning attempt could not assign the order. - `type` string, nullable: Field to specify if the order is a pick/drop - `type_index` integer, nullable: Field to specify if the order is a pick/drop - `started_at` string, nullable: Timestamp at which the order tracking started - `completed_at` string, nullable: Timestamp at which the order was completed - `cancelled_at` string, nullable: Timestamp at which the order was cancelled - `expected_service_time` integer, nullable: Time in seconds that the driver is expected to spend at the location when fulfilling the order - `estimate` union: Object containing the estimate information for the order that has not been completed - OrderListEstimate - `start_at` string, nullable: Deprecated: use `start_by`. Always returns the same value as `start_by`. - `start_by` string, nullable: Latest time the worker can leave their current (or planned start) location and still reach this order by its `scheduled_at`, following the route sequence and the remaining service time at earlier stops. Computed by planning and once at the first tracking ETA, which uses traffic for the planned arrival time. `null` when the order has no `scheduled_at`. - `arrive_at` string, nullable: Estimated timestamp by which a driver should arrive at order destination - `distance` integer, nullable: Estimated total distance that the driver should travel - `duration` integer, nullable: Estimated total time that the driver should spend to fulfill all orders in the route - `initial_arrive_at` string, nullable: Initial Estimated timestamp by which a driver should arrive at the destination - `current_worker_location` union: Current Worker location details - DriverLocation - … - unknown - unknown - `actual_service_time` integer, nullable: Time in seconds that the driver is actually spent at the location when fulfilling the order - `tracked_service_time` integer, nullable: Time in seconds that the driver was tracked at the location when fulfilling the order - `distance` integer, nullable: Total distance in meters travelled by the driver to reach the order location - `duration` integer, nullable: Total time in seconds spent on the order. - `created_by` union: Source of the route creation. This can be a user, system, or any other entity responsible for creating the route. - Source - `source` string, nullable: Source of the request - `timestamp` string, nullable: Time when request was made - `ip-address` string, nullable: IP address of source - `device_id` string, nullable: Id of the device that made the request - `driver_handle` string, nullable: Id of the driver who made the request - `user_id` string, nullable: Id of the user who made the request - `email` string, nullable: Email of the user who made the request - unknown - `ops_group_handle` string: URL safe unique identifier for the ops group to which the orders in the route are associated - `track_mode` 'full_shift' | 'on_shift' | 'pre_shift' | 'null', nullable: Value representing whether the route is tracked in on_shift, pre_shift or full_shift mode - `plan_mode` 'on_demand' | 'scheduled' | 'manual' | 'null', nullable: Value indicating how the orders in the route were planned - `started_at` string, nullable: Timestamp at which the route tracking started - `assigned_at` string, nullable: Timestamp at which the route was assigned to a driver - `planned_at` string, nullable: Timestamp at which the orders were planned into this route - `completed_at` string, nullable: Timestamp at which the route was completed - `device_id` string, nullable: Unique identifier for a device - `driver_handle` string, nullable: Unique customer provided identifier for the driver - `worker_handle` string, nullable: Unique customer provided identifier for the worker - `metadata` object, nullable: Additional customer provided information about the route - `region` union: City, state, and country where the orders in the route are being fulfilled - Region - `country` string, required: Country - `city` string, nullable: City - `state` string, nullable: State - unknown - `distance` integer, nullable: Actual distance travelled by the driver to fulfill all orders in the route - `duration` integer, nullable: Actual time spent by the driver to fulfill all orders in the route - `estimate` union: Object containing the estimate information for routes that have not been completed - RouteListEstimate - `start_by` string, nullable: Latest time the worker can leave the planned start location and still reach every scheduled order in the route on time, following the route sequence and service times. Orders without `scheduled_at` use a placeholder deadline. Computed at planning. - `distance` integer, required: Estimated total distance that the driver should travel in the route - `duration` integer, required: Estimated total time that the driver should spend to fulfill all orders in the route - unknown - `plan_id` string, nullable: Unique identifier for the plan to which the route belongs to - `device_switch_mode` unknown - `candidate_devices` string[], nullable: List of devices among which the route is expected to be tracked - `completion_source` string, nullable: Source of the route completion - `scheduled_start_at` string, nullable: Scheduled start time of the route - `pagination_token` string, nullable ## Other responses - `400`: Validation error - `401`: Authentication error --- [API](https://skmtc.dev/hypertrack/apis/hypertrack-api.md) - [All operations](https://skmtc.dev/hypertrack/apis/hypertrack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hypertrack/apis/hypertrack-api/revisions/389326c4c9c8?raw)