---
title: "List plans"
method: GET
path: "/plans"
tags: ["Plans"]
---

# List plans

`GET /plans`

## Request

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

## Query parameters

- `pageToken` string
- `maxPageSize` number
- `filter` object
  - `title` string: Filter by title, exact match
  - `startsGte` string: Search for plans that start after this date, inclusive. The date must be in the format YYYY-MM-DD.
  - `startsLte` string: Search for plans that start before this date,inclusive. The date must be in the format YYYY-MM-DD.

## Response `200`

Success

- object: Success
  - `plans` PlanSchema[], required: The plans list.
    - `id` string, required
    - `title` string, required: The title of the plan.
    - `starts` DateSchema, required: A date.
      - `day` integer, required: The day of the date.
      - `month` integer, required: The month of the date.
      - `year` integer, required: The year of the date.
    - `depot` string, required
    - `distributed` boolean, required: Whether the plan has been distributed.
    - `writable` boolean, required: Whether the plan is writable using the normal Plan APIs. If this is false, you will need to use the [Live Plan APIs](/api/v1#tag/Live-Plans) to edit the plan. Any plan created before 2023-04-01 is not writable.
    - `optimization` 'creating' | 'editing' | 'preview' | 'optimized' | 'optimizing', nullable, required: The optimization state of the plan.
    - `drivers` DriverIdSchema[], required: The driver IDs of the plan, in the format drivers/<id>.
    - `routes` RouteIdSchema[], required: The route IDs of the plan, in the format routes/<id>.
    - `routeOverrides` object, nullable, required: Settings for this plan to override default route configurations.
      - `startTime` object, nullable, required: Time of day in hours and minutes. Uses a 24 hour clock.
        - `hour` integer, required: Hour of the day
        - `minute` integer, required: Minute of the hour
      - `endTime` object, nullable, required: Time of day in hours and minutes. Uses a 24 hour clock.
        - `hour` integer, required: Hour of the day
        - `minute` integer, required: Minute of the hour
      - `startAddress` object, nullable, required: The address of the stop.
        - `address` string, required: The address of the stop.
        - `addressLineOne` string, required: The first line of the address.
        - `addressLineTwo` string, required: The second line of the address.
        - `latitude` number, nullable, required: The latitude of the address in decimal degrees.
        - `longitude` number, nullable, required: The longitude of the address in decimal degrees.
        - `placeId` string, nullable, required: The identifier of the place corresponding to this stop on Google Places
        - `placeTypes` string[], required: Array of strings that is provided by the Google AutoCompleteAPI
      - `endAddress` object, nullable, required: The address of the stop.
        - `address` string, required: The address of the stop.
        - `addressLineOne` string, required: The first line of the address.
        - `addressLineTwo` string, required: The second line of the address.
        - `latitude` number, nullable, required: The latitude of the address in decimal degrees.
        - `longitude` number, nullable, required: The longitude of the address in decimal degrees.
        - `placeId` string, nullable, required: The identifier of the place corresponding to this stop on Google Places
        - `placeTypes` string[], required: Array of strings that is provided by the Google AutoCompleteAPI
      - `maxStops` integer, nullable, required: Maximum number of Stops per route.
      - `drivingSpeed` 'slower' | 'average' | 'faster', nullable, required: The relative driving speed compared to others.
      - `deliverySpeed` 'slower' | 'average' | 'faster', nullable, required: The relative delivery speed compared to others.
      - `vehicleType` 'bike' | 'scooter' | 'car' | 'small_truck' | 'truck' | 'electric_cargo_bike', nullable, required: The vehicle type used for deliveries.
      - `optimizationSettings` object, required: Optimization settings for the plan.
        - `objective` 'minimize_drivers' | 'distribute_services', required: The primary optimization objective.
        - `subObjective` 'equalize_workload' | 'equalize_time' | 'maximize_efficiency', nullable: The secondary optimization objective.
  - `nextPageToken` string, nullable, required: The next page token.

## Other responses

- `400`: Query parameters are invalid
- `401`: Unauthorized
- `500`: An internal server error occurred
- `default`: The default error model

---

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