--- title: "Get Plan" method: GET path: "/orders/plans/{plan_id}" tags: ["Orders"] --- # Get Plan `GET /orders/plans/{plan_id}` ## Request - Base URL: `https://v3.api.hypertrack.com` - URL: `https://v3.api.hypertrack.com/orders/plans/{plan_id}` - Auth: one of: - HTTP basic - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) API to fetch plan by Plan ID Unplanned orders may include planning_failure_reason, a customer-facing explanation of why automated planning could not assign the order. ## Path parameters - `plan_id` string, required ## Response `200` Successful response - GetPlanResponse - `plan_id` string, required: Unique ID of the plan. - `sequence_number` integer, required: Sequence number of the latest planning run. - `routes` PlanRoute[]: List of routes planned as part of this plan. - `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', required: 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, required: 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, required: 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 - `unplanned_orders` OrderObjectMini[]: List of orders which has not been planned. - `order_handle` string, required: Unique handle of the order - `status` 'completed' | 'cancelled' | 'disabled' | 'ongoing' | 'unplanned' | 'assigned' | 'planned' | 'dispatched' | 'summarizing', required: Current state of the order - `type` string, nullable: Type of order - `type_index` integer, nullable: Index to help distinguish similar handle and type orders - `plan_mode` string, nullable: Mode with which the order was planned - `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. - `status` 'failed' | 'completed' | 'planning', required: Status of the plan based on the latest planning run. - `started_at` string, required: Timestamp representing the start time of latest planning run for the plan. - `created_at` string, required: Timestamp representing the creation time of the plan. - `ops_group_handle` string, required: Unique Handle of ops group handle of the plan. - `fulfillment_date` string, required: Date (YYYY-MM-DD) representing the fulfillment date of plan. - `failure_reason` string: Reason of failure of the latest planning run for plan. Sample values are listed below.
- `summary` PlanSummary, required - `orders` PlanSummaryOrders, required - `total` integer, required: Total number of orders under consideration for planning - `planned` integer, required: Total number of orders successfully planned - `unplanned` integer, required: Total number of orders which could not be planned - `assigned` integer, required: Total number of orders which were successfully assigned to any driver - `completed` integer, required: Total number of orders which have been completed - `cancelled` integer, required: Total number of orders which have been cancelled - `estimate` PlanSummaryEstimate, required - `distance` integer, required: Total distance estimated to be travelled. - `duration` integer, required: Total duration estimated to be travelled. - `distance` integer, required: Total distance travelled for completed and cancelled orders - `duration` integer, required: Total duration travelled for completed and cancelled orders - `routes` integer, required: Total number of routes planned. - `drivers` integer, required: Total number of drivers assigned ## Other responses - `400`: Validation error - `401`: Authentication error - `404`: Not found --- [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)