> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run status

> Poll the status of an async run

<Info>
  **V3 is in beta.** General availability (GA) is planned for January 2027.
</Info>


## OpenAPI

````yaml vrp-v3-runs GET /v3/routing/runs/{id}
openapi: 3.1.0
info:
  title: 'Solvice Routing API: async runs'
  description: >-
    Run a routing problem in the background: submit it, poll the run, then fetch
    the plan. The run takes the same request body as `POST /v3/routing/solve`
    and its result is the same `SolveResponse`. Served by the API gateway at
    `https://api.solvice.io`, not by the solver.
  contact:
    name: Solvice
    url: https://www.solvice.io
  license:
    name: Proprietary
  version: 3.0.0
servers:
  - url: https://api.solvice.io
    description: Production — Solvice API gateway
security:
  - apiKey: []
tags:
  - name: Runs
    description: Async routing runs
paths:
  /v3/routing/runs/{id}:
    get:
      tags:
        - Runs
      summary: Get the status of a run
      description: >-
        Returns the run. A run that was not finished is checked against its
        worker on every call: if the worker is gone, the run turns `failed` with
        `worker_lost`.
      operationId: getRoutingRunStatus
      parameters:
        - name: id
          in: path
          required: true
          description: The run id returned by `POST /v3/routing/runs`.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
              examples:
                running:
                  summary: Running
                  value:
                    id: d28568b1-34cc-4f89-b10b-dc24b26a8275
                    status: running
                    links:
                      self: /v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275
                      result: >-
                        /v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275/result
                    started_at: '2026-10-15T07:40:59Z'
                succeeded:
                  summary: Succeeded
                  value:
                    id: d28568b1-34cc-4f89-b10b-dc24b26a8275
                    status: succeeded
                    links:
                      self: /v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275
                      result: >-
                        /v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275/result
                    started_at: '2026-10-15T07:40:59Z'
                    finished_at: '2026-10-15T07:41:00Z'
                    expires_at: '2027-10-15T07:41:00Z'
        '400':
          description: '`id` is not a UUID. Body: `{"error": "Invalid UUID string: …"}`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                error: 'Invalid UUID string: not-a-uuid'
        '401':
          description: >-
            Missing or invalid API key. Returned by the API gateway, so it does
            not use the `ErrorBody` shape and can have an empty body. Branch on
            the HTTP status.
        '404':
          description: >-
            No run with this id on your account. Runs of other accounts are also
            `404`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                message: 'not_found: routing run d28568b1-34cc-4f89-b10b-dc24b26a8275'
                error: GATEWAY_ERROR
components:
  schemas:
    Run:
      type: object
      description: One async run.
      required:
        - id
        - status
        - links
      properties:
        id:
          type: string
          format: uuid
          description: The run id. Use it in the paths of the other endpoints.
          example: d28568b1-34cc-4f89-b10b-dc24b26a8275
        status:
          $ref: '#/components/schemas/RunStatus'
        links:
          $ref: '#/components/schemas/RunLinks'
        error:
          $ref: '#/components/schemas/RunError'
          description: Present when `status` is `failed`.
        started_at:
          type: string
          format: date-time
          description: >-
            When a worker claimed the run, in UTC. Absent while the run is
            `queued`.
          example: '2026-10-15T07:40:59Z'
        finished_at:
          type: string
          format: date-time
          description: When the run reached a final state, in UTC. Absent before then.
          example: '2026-10-15T07:41:00Z'
        expires_at:
          type: string
          format: date-time
          description: >-
            When the run and its plan are deleted: `finished_at` plus 365 days.
            Absent before the run is final.
          example: '2027-10-15T07:41:00Z'
    GatewayError:
      type: object
      description: >-
        The gateway's own error answer on `/v3/routing/runs*`, not the
        `ErrorBody` shape. `message` starts with a code (`not_found`,
        `run_not_finished`, `no_result`), a colon and a sentence; branch on the
        HTTP status and that code.
      required:
        - error
      properties:
        error:
          type: string
          description: '`GATEWAY_ERROR`, or the reason for a malformed `id`.'
          example: GATEWAY_ERROR
        message:
          type: string
          description: Absent on a malformed `id`.
          example: 'not_found: routing run d28568b1-34cc-4f89-b10b-dc24b26a8275'
    RunStatus:
      type: string
      enum:
        - queued
        - running
        - succeeded
        - failed
        - cancelled
      description: >-
        Where a run is. `queued` until a worker claims it, then `running`.
        `succeeded`, `failed` and `cancelled` are final.
    RunLinks:
      type: object
      description: Paths of the run, relative to the API host.
      required:
        - self
        - result
      properties:
        self:
          type: string
          description: '`GET` it to poll the run.'
          example: /v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275
        result:
          type: string
          description: '`GET` it for the plan once the run `succeeded`.'
          example: /v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275/result
    RunError:
      type: object
      description: Why a run `failed`, in the `ErrorBody` shape.
      required:
        - status
        - code
        - message
      properties:
        status:
          type: string
          description: The HTTP status as text.
          example: INTERNAL_SERVER_ERROR
        code:
          type: string
          description: >-
            `invalid_request`, `matrix_provider_error`, `internal` or
            `worker_lost`. `worker_lost`: the worker stopped before it finished,
            or the run exceeded 6,000 s.
          example: worker_lost
        message:
          type: string
          description: Human-readable summary.
          example: the worker stopped before finishing
        request_id:
          type:
            - string
            - 'null'
          description: The `X-Request-Id` of the request that submitted the run.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
          description: One entry per problem found in the request, as in `ErrorBody`.
    ErrorItem:
      type: object
      description: One problem in a request.
      required:
        - code
        - message
      properties:
        actual:
          type:
            - integer
            - 'null'
          format: int64
          description: '`limit_exceeded` only: the count this request has.'
          minimum: 0
        code:
          $ref: '#/components/schemas/ErrorItemCode'
          description: What is wrong.
        limit:
          type:
            - integer
            - 'null'
          format: int64
          description: '`limit_exceeded` only: the published cap.'
          minimum: 0
        message:
          type: string
          description: Human-readable description.
        pointer:
          type:
            - string
            - 'null'
          description: |-
            RFC 6901 JSON Pointer into the request body, when the problem has a
            location. It is relative to the root of the body, so a field of the
            problem reads `/problem/...` (e.g.
            `"/problem/vehicles/0/shifts/0/from"`).
    ErrorItemCode:
      type: string
      description: |-
        The `code` of one `errors[]` item. Clients should accept values they do
        not know yet.
      enum:
        - invalid_json
        - invalid_type
        - unknown_field
        - missing_field
        - invalid_value
        - not_supported
        - out_of_range
        - duplicate_id
        - unknown_reference
        - conflicting_fields
        - limit_exceeded
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.