---
title: "Get Plans"
method: GET
path: "/orders/plans"
tags: ["Orders"]
---

# Get Plans

`GET /orders/plans`

## Request

- Base URL: `https://v3.api.hypertrack.com`
- URL: `https://v3.api.hypertrack.com/orders/plans`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
- TypeScript: <https://skmtc.dev/hypertrack/apis/hypertrack-api/docs/orders/plans/get.ts> (a function with typed inputs; its response is checked against the schema)

API to fetch list of plans based on a set of filters Unplanned orders may include planning_failure_reason, a customer-facing explanation of why automated planning could not assign the order.

## Query parameters

- `fulfillment_date` string, nullable
- `ops_group_handle` string, nullable
- `pagination_token` string, nullable
- `status` 'failed' | 'completed' | 'planning' | 'null', nullable
- `sort_direction` 'desc' | 'asc' | 'null', nullable
- `include_summary` boolean, nullable
- `limit` integer, nullable

## Response `200`

Successful response

- GetPlansResponse
  - `plans` PlanListResponse[], required: List of plan objects
    - `plan_id` string, required: Unique ID of the plan.
    - `sequence_number` integer, required: Sequence number of the latest planning run.
    - `routes` PlanListRoute[]: 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
    - `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.</br><ul><li> Ops group location cannot be the same as an order location</li> <li>Could not resolve country when planning orders</li> <li>Could not resolve ISO3 country_code for country</li> <li>Route planning is currently not enabled for country</li></ul>
    - `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
  - `pagination_token` string, nullable: Token representing the pointer to the last object in current page, in case more pages are present

## 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)