---
title: "Get Optimisation Job by ID"
method: GET
path: "/plans/optimise/{id}"
tags: ["Plans"]
---

# Get Optimisation Job by ID

`GET /plans/optimise/{id}`

## Request

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

Check whether an optimisation started with `POST /plans/optimise/orders` or `POST /plans/optimise/orders-for-ids` is still running. Pass the `optimisation.id` (a UUID) that the call returned. The response has the same shape as that call's response: `optimisation.in_progress`, plus the `plan` the job writes into. `plan.dispatched` becomes `true` once the plan is dispatched, for example by `auto_dispatch`.

`in_progress: false` means the job has stopped, not that it succeeded. A failed optimisation also reports `false`, and this endpoint does not tell you which outcome you got. Fetch `GET /plans/{id}` with `plan.id` to see the result, and use the polling cadence and hard timeout described under `POST /plans/optimise/orders`. An optimisation id that does not exist, or that belongs to another depot, answers `404 RESOURCE_NOT_FOUND`.

## Path parameters

- `id` string, required

## Response `200`

Successful response

- PlanOptimisationResponse
  - `optimisation` object, required
    - `id` string, uuid, required
    - `in_progress` boolean, required
  - `plan` object, required
    - `id` integer, required
    - `dispatched` boolean, required
  - `errors` object[]: Orders left out of the optimisation, each with the reason. May be absent.
    - `name` string, required: Reason code (e.g. `IN_ANOTHER_PLAN`).
    - `description` string, required: Human-readable explanation.
    - `details` object, required
      - `id` integer, required: Order id.
      - `order_number` string, nullable, required: Order number.
      - `plan_ids` integer[]: Plans the order already belongs to.

## Other responses

- `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).
- `404`: The requested resource was not found.
- `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)