--- title: "Get Orders" method: GET path: "/orders/" tags: ["Orders"] --- # Get Orders `GET /orders/` ## Request - Base URL: `https://v3.api.hypertrack.com` - URL: `https://v3.api.hypertrack.com/orders/` - Auth: one of: - HTTP basic - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) ### Planning failure reasons When an order is left unplanned by automated planning, `planning_failure_reason` may contain one of these values: - `No Worker was available for this plan.` - `No Worker schedule overlaps with this order's time window.` - `This order is outside the available Worker working hours.` - `Worker location is unavailable, so travel time could not be evaluated.` - `Worker start location is unavailable for the configured route start setting.` - `No Worker supports the required product type for this order.` - `Route was being modified concurrently and this order needs to be re-planned.` - `The optimizer dropped this order to satisfy planning constraints for the overall plan.` - `The optimizer could not find a feasible plan for the provided constraints.` - `Travel time calculation failed for this planning attempt.` - `Ops group configuration is incomplete for automated planning.` - `Assigning this order would exceed route or Worker capacity.` - `No Worker can reach this order before scheduled_at.` - `Assigning this order would delay an already planned downstream order.` - `Assigning this order would exceed the Worker's shift end time.` - `Existing assigned route conflicts with the Worker schedule, so this order could not be inserted into the plan.` - `Existing assigned route exceeds the Worker's shift, so this order could not be inserted into the plan.` - `Existing assigned route has conflicting appointment windows, so this order could not be inserted into the plan.` - `Existing assigned route exceeds route or Worker capacity, so this order could not be inserted into the plan.` - `Existing assigned route exceeds the configured maximum route distance, so this order could not be inserted into the plan.` - `Existing assigned routes were preserved, so this order could not be inserted into the plan.` - `Assigning this order would exceed the configured maximum route distance.` - `The optimizer reached its planning limit before it could assign this order.` - `Automated planning could not assign this order with the provided constraints.` ## Query parameters - `worker_handle` string, nullable - `place_handle` string, nullable - `search_term` string, nullable - `ops_group_handle` string, nullable - `order_metadata_filter` string, nullable - `risk_status` string, nullable - `region_filter` string, nullable - `status` string, nullable - `device_id` string, nullable - `destination_geohash` string, nullable - `plan_mode` unknown - `plan_id` string, nullable - `route_handle` string, nullable - `track_mode` unknown - `device_switch_mode` unknown - `created_at_date` string, nullable - `created_at_from` string, nullable - `created_at_to` string, nullable - `planned_at_date` string, nullable - `planned_at_from` string, nullable - `planned_at_to` string, nullable - `scheduled_at_date` string, nullable - `scheduled_at_date_without_tz` string, nullable - `completed_at_date_without_tz` string, nullable - `scheduled_at_from` string, nullable - `scheduled_at_to` string, nullable - `scheduled_at_without_tz_from` string, nullable - `scheduled_at_without_tz_to` string, nullable - `cancelled_at_date` string, nullable - `cancelled_at_from` string, nullable - `cancelled_at_to` string, nullable - `completed_at_date` string, nullable - `completed_at_from` string, nullable - `completed_at_to` string, nullable - `rescheduled_marked_at_date` string, nullable - `rescheduled_marked_at_from` string, nullable - `rescheduled_marked_at_to` string, nullable - `route_started_at_date` string, nullable - `route_started_at_from` string, nullable - `route_started_at_to` string, nullable - `completed_at_without_tz_from` string, nullable - `completed_at_without_tz_to` string, nullable - `created_at_without_tz_from` string, nullable - `created_at_without_tz_to` string, nullable - `created_at_date_without_tz` string, nullable - `driver_handle` string, nullable - `sort_direction` unknown - `fulfillment_attempt` integer, nullable - `aggregate` boolean, nullable - `limit` integer, nullable - `pagination_token` string, nullable - `send_outage` boolean, nullable - `tracking_status` 'tracked' | 'untracked' | 'null', nullable - `filter_outage_category` string, nullable - `worker_profile_filter` string, Encoded JSON, nullable - `worker_inside_destination` boolean, nullable - `order_handle` string, nullable ## Response `200` Successful response - GetOrdersResponse - `orders` OrderResponse[], nullable - `timezone` string, nullable: Time zone - `order_handle` string, required: Unique customer provided identifier for an order - `status` 'planned' | 'assigned' | 'dispatched' | 'ongoing' | 'disabled' | 'cancelled' | 'completed' | 'summarizing' | 'unplanned', required: Current state of the order - `unplanned`, `planned`, `assigned`, `ongoing`, `completed`, `cancelled` - `destination` OrderDestinationSpecialType, required - `geofence_id` string, nullable: Geofence ID to extract geometry from - `place_handle` string, nullable: Place Handle to extract geometry from - `address` string, nullable: Address for the order destination - `geometry` union, required: GeoJSON representation of point geometry for the order destination - PointGeometry - `coordinates` number[], required: Location coordinates represented as [longitude, latitude] - `type` 'Point': Geometry type - PolygonGeometry - `type` 'Polygon', required: Geometry type - `coordinates` array[], required: Location coordinates represented as [[[longitude, latitude], [lon, lat]...]] - array[] - … - `place_id` string, nullable: Place ID - `radius` integer, nullable: Radius of the circular geofence representing the order destination - `fulfillment_attempt` integer, nullable: Number identifying the attempt count for the order - `risk_status` boolean, nullable: Flag indicating whether the order is at risk - `ops_group_handle` string, nullable: Unique identifier for the ops group to which the orders in the route are associated - `plan_mode` unknown - `plan_id` string, nullable: Order plans identifier - `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. - `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 - `place_handle` string, nullable: Unique customer provided identifier of the place - `created_at` string, nullable: Timestamp at which the order was created - `started_at` string, nullable: Timestamp at which the order tracking started - `assigned_at` string, nullable: Timestamp at which the order was assigned to a driver - `driver_name` string, nullable: Customer provided name for the driver - `planned_at` string, nullable: Timestamp at which the order was planned into a route - `scheduled_at` string, nullable: Timestamp by which the order should be fulfilled to meet the customer promise - `scheduled_after` string, nullable: Timestamp after which the order should be fulfilled to meet the customer promise - `completed_at` string, nullable: Timestamp at which the order was completed - `cancelled_at` string, nullable: Timestamp at which the order was cancelled - `disabled_at` string, nullable: Timestamp at which the order was disabled so that it can be fulfillment later - `enabled_at` string, nullable: Timestamp at which the disabled order was enabled for fulfillment - `arrived_at` string, nullable: Timestamp at which the driver arrived at the order fulfillment location - `exited_at` string, nullable: Timestamp at which the driver exited from the order fulfillment location - `metadata` object, nullable: Additional customer provided information about the order - `risks` object, nullable: Object containing different risk statuses for the order - `expected_service_time` integer, nullable: Time in seconds that the driver is expected to spend at the location when fulfilling the order - `product_type` string[], nullable: List of customer provided product/service types used when matching orders to a driver - `type` unknown - `type_index` integer, nullable: Field to specify the index of type - `capacity_used` integer, nullable: Volumetric unit occupied by the order - `region` union: City, state, and country where the orders needs to be fulfilled - Region - `country` string, required: Country - `city` string, nullable: City - `state` string, nullable: State - unknown - `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. - `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 - `geometry` LocationGeometryResponse, required - … - `bearing` number, required: Bearing of the driver - `accuracy` number, required: Accuracy of location the driver - `speed` number, required: Speed of the driver - `recorded_at` string, required: Time when the location of the driver was recorded - unknown - unknown - `share_url` string, nullable: Shareable URL for the consumer to track the live movement of the drive after the order is dispatched - `route_handle` string, nullable: Unique identifier for the route - `track_mode` 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 - `tracking_rate` number, nullable: Indicates the ratio of time tracked to expected tracking time of order. Values lie between 0.0 and 1.0 - `time_to_first_event` number, nullable: Time in seconds to receive first event from device after order start - `time_to_first_location` number, nullable: Time in seconds to receive first location from device after order start - `created_by` union: Source of the order creation. This can be a user, system, or any other entity responsible for creating the order. - 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 - `outage_summary` OrderOutageSummary[], nullable: List of outages experienced during the specified time range. - `duration` integer, required: Sum total duration of all outages experienced with this `code` in the specified time range. - `distance` integer: Sum total (estimated) distance covered during all outages experienced with this `code` in the specified time range. - `code` string, required: Code indicating the type of outage - `label` string, required: Text indicating the type of outage - `description` string, required: Text describing the outage. - `category` 'behavioural' | 'adversarial' | 'reachability' | 'os' | 'sporadic' | 'null', nullable: String indicating the category of outage - `embed_url` string, nullable: Embeddable URL for the ops team to view order timeline - `device_switch_mode` unknown - `tasks` OrderTask[], nullable: List of tasks associated with the order. - `label` string, required: Type of task to be created for the order. - `task_definition_id` string, nullable: Id of the tasks definition from which this task is picked - `description` string, nullable: Description of the task type. - `metadata` object, nullable: Additional metadata for the task. - `priority` 'none' | 'low' | 'medium' | 'high' | 'null', nullable: Priority of the task. Valid values are none, low, medium, high. - `task_id` string, required: Unique identifier for the created task. - `status` string, nullable: Status of the task. Valid values are pending, ongoing, completed, cancelled. - `priority` unknown - `worker_profile` object, nullable: Metadata associated with a driver - `rescheduled_marked_at` string, nullable: Timestamp at which the order was rescheduled - `cancellation_source` object, nullable: Detail about how order got cancelled - `cancellation_reason` string, nullable: Customer-reported reason why the shift did not occur as planned: `no_show`, `worker_cancelled`, `client_cancelled`, `other`. Consumers must accept new values. - `timesheets` union[], nullable: Timesheet entries for the order. Includes HyperTrack-computed (HypertrackLocationTimesheet) and customer-provided entries. - union - HypertrackLocationTimesheet - `source` string, required: Always hypertrack-location. Identifies this as a HyperTrack-computed entry. - `type` string, required: Always location. Distinguishes this computation type from future types. - `start_time` string, nullable: ISO 8601 timestamp when the worker arrived on site (first geofence entry). Null if the worker never entered the destination geofence. - `end_time` string, nullable: ISO 8601 timestamp when the worker left the site (last geofence exit). Null if the worker was still inside at order closure. - `total_duration_on_premises` integer, required: Total seconds the worker spent at the destination (sum of geofence visit durations). - `total_break_duration` integer, required: Residual seconds not at the destination. Equals (end_time - start_time) - total_duration_on_premises. - `breaks` BreakEntry[], nullable: Geofence exit→re-entry windows representing time away from the destination. Each entry has start_time, end_time, and duration (seconds). Null when there are no exit→re-entry gaps. - `type` string, required: Break type (e.g. "meal", "rest"). - `start_time` string, required: ISO 8601 timestamp when the break started. - `end_time` string, required: ISO 8601 timestamp when the break ended. - `duration` integer, required: Break duration in seconds. - `finalized` boolean, required: Always true. Signals this entry was computed at order completion and will not change. - object - `pagination_token` string, nullable - `aggregate` union - OrderAggregate - `orders` OrderCountAggregateModel, required - `total` integer, required: Total number of orders - `unplanned` integer, required: Total unplanned orders - `planned` integer, required: Total planned orders - `assigned` integer, required: Total assigned orders - `ongoing` integer, required: Total ongoing orders - `disabled` integer, required: Total disabled orders - `rescheduled` integer, required: Total rescheduled orders - `completed` integer, required: Total completed orders - `cancelled` integer, required: Total cancelled orders - `tracked` integer, required: Total tracked orders - `on_shift` integer, required: Total on_shift orders - `pre_shift` integer, required: Total pre_shift orders - `full_shift` integer, required: Total full_shift orders - `arrived` integer, required: Total arrived orders - `on_time` integer, required: Orders that arrived within a 10-minute window of the scheduled time - `worked` integer, required: Orders that had a service time within a 45-minute window of the expected service time - `ttfe30_orders_from_start` integer, required: Orders that received a location event within 30 minutes of the start time if no scheduled time is present - `ttfe30_orders_before_schedule_time` integer, required: Orders that have received their first event at least 30 minutes before the order's scheduled time - `tasks` union: Fields containing status level count of tasks along with total tasks. - OrderTaskAggregate - `total` integer, required: Total number of tasks - `status_counts` object, required: Counts of tasks by status - unknown - `distance` union: Stats related to the orders distance - BaseStats - `mean` number, nullable: Average value for the metric - `min` number, nullable: Minimum value for the metric - `max` number, nullable: Maximum value for the metric - `stdev` number, nullable: Standard deviation for the metric - `mean_by_driver` number, nullable: Average value per worker for the metric - unknown - `duration` union: Stats related to the orders duration - BaseStats - `mean` number, nullable: Average value for the metric - `min` number, nullable: Minimum value for the metric - `max` number, nullable: Maximum value for the metric - `stdev` number, nullable: Standard deviation for the metric - `mean_by_driver` number, nullable: Average value per worker for the metric - unknown - `tracked_duration` integer, nullable: Total Tracked duration for the orders - `active_duration` integer, nullable: Active duration for the orders - `deviation` union: Stats related to the orders deviation - BaseStats - `mean` number, nullable: Average value for the metric - `min` number, nullable: Minimum value for the metric - `max` number, nullable: Maximum value for the metric - `stdev` number, nullable: Standard deviation for the metric - `mean_by_driver` number, nullable: Average value per worker for the metric - unknown - `service_time` union: Stats related to the orders service time - BaseStats - `mean` number, nullable: Average value for the metric - `min` number, nullable: Minimum value for the metric - `max` number, nullable: Maximum value for the metric - `stdev` number, nullable: Standard deviation for the metric - `mean_by_driver` number, nullable: Average value per worker for the metric - unknown - `completion_delay` union: Stats related to the orders completion delay - BaseStats - `mean` number, nullable: Average value for the metric - `min` number, nullable: Minimum value for the metric - `max` number, nullable: Maximum value for the metric - `stdev` number, nullable: Standard deviation for the metric - `mean_by_driver` number, nullable: Average value per worker for the metric - unknown - `drivers` union: Total number of drivers - DriverTotal - `total` integer, required: Total number of workers - unknown - `workers` union: Total number of workers - DriverTotal - `total` integer, required: Total number of workers - unknown - `tracking_rate` number, nullable: Indicates the ratio of time tracked to expected tracking time of all orders combined. Values lie between 0.0 and 1.0 - `routes` union: Total number of routes - RouteTotal - `total` integer, required: Total number of routes - unknown - `outage_summary` OrderOutageSummaryAgg[], nullable: List of outages experienced during the specified time range. - `duration` integer, required: Sum total duration of all outages experienced with this `code` in the specified time range. - `distance` integer: Sum total (estimated) distance covered during all outages experienced with this `code` in the specified time range. - `code` string, required: Code indicating the type of outage - `label` string, required: Text indicating the type of outage - `description` string, required: Text describing the outage. - `category` 'behavioural' | 'adversarial' | 'reachability' | 'os' | 'sporadic' | 'null', nullable: String indicating the category of outage - `duration_in_tracked_orders` integer: Sum total duration of all outages experienced by tracked orders with this `code` in the specified time range. - `duration_in_untracked_orders` integer: Sum total duration of all outages experienced by untracked orders with this `code` in the specified time range. - `orders_count_with_ttfe` union: Orders aggregation metrics based on their first device event. - OrdersTotalWithTTFE - `within_10_min` integer, required: Total number of orders where the first device event was received within 10 minutes of tracking - `within_20_min` integer, required: Total number of orders where the first device event was received within 20 minutes of tracking - `within_30_min` integer, required: Total number of orders where the first device event was received within 30 minutes of tracking. - `within_40_min` integer, required: Total number of orders where the first device event was received within 40 minutes of tracking. - `within_50_min` integer, required: Total number of orders where the first device event was received within 50 minutes of tracking. - `within_60_min` integer, required: Total number of orders where the first device event was received within 60 minutes of tracking. - `within_70_min` integer, required: Total number of orders where the first device event was received within 70 minutes of tracking. - `within_80_min` integer, required: Total number of orders where the first device event was received within 80 minutes of tracking. - `within_90_min` integer, required: Total number of orders where the first device event was received within 90 minutes of tracking. - unknown - unknown ## 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)