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

# Get Plans Page

`GET /plans`

## Request

- Base URL: `https://api.smartroutes.io/v2`
- URL: `https://api.smartroutes.io/v2/plans`
- Auth: none declared

Page through the plans in your depot, most recently updated first. Each plan carries its `dispatched` flag, `total_time`, `created` and `updated` timestamps, and a summary of each of its routes: the routes from its current optimisation, plus any route dispatched from an earlier optimisation of the same plan. Route summaries give a stop count, not the stops themselves. To get stops, orders and proof of delivery, call `GET /plans/{id}` or `GET /routes/{id}`.

Results are paged with the `Link` header and `limit` (1–100, default 100). See [Paging](#section/Getting-started/Paging). Keep following the `rel=next` URL until a response has none. `updated_at_min` returns only plans whose own `updated` timestamp is at or after the given time, and the `rel=next` URL carries it forward. A malformed `page_info` is rejected with `400 INVALID_INPUT`. An `updated_at_min` in an unrecognised format, or a `limit` outside 1–100, is ignored rather than rejected.

A plan whose optimisation has not produced a result yet is listed with only `id`, `total_time: 0` and an empty `routes` array. Deleted plans drop out of the list; the [`plans.deleted`](#tag/Webhooks/operation/plans.deleted) webhook tells you when a plan is deleted.

## Query parameters

- `page_info` string: Information about the page for pagination. Generated by the OpenAPI
- `updated_at_min` string, date-time: Minimum updated date and time for filtering.
- `limit` integer: Maximum number of plans to retrieve per page.

## Response `200`

Successful response

## Other responses

- `400`: Invalid input. The request body failed validation.
- `403`: Forbidden. Returned for rate-limit exhaustion (`name = FORBIDDEN`, with `details.retry_after_seconds` and `Retry-After` header) and permission gate failures (`name = PERMISSION`). Inspect `name` to disambiguate. Send `x-sr-api-features: rate-limit-429` to receive `429 RATE_LIMIT_EXCEEDED` for the rate-limit case instead, leaving `403` to mean permission failures only — see [API Features](#section/Getting-started/API-Features).
- `429`: Rate limit exceeded (`name = RATE_LIMIT_EXCEEDED`). **Only returned to callers that opt in** with the `x-sr-api-features: rate-limit-429` request header; without it the same condition returns `403` with `name = FORBIDDEN` and an otherwise identical body. See [API Features](#section/Getting-started/API-Features).
- `500`: An unexpected server error occurred. The body carries only `name` and `description`: internal details are never returned.

---

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