GET /api/v1/businesses/{id}/planning/jobs/{job}

GET/api/v1/businesses/{id}/planning/jobs/{job}

Integration permission: planning.read. Administrator membership grants management access only to this business.

Authentication

Authorized business administrator session, or a business API key with planning.read.

Parameters

Parameter	In	Type	Description
`id`Required	path	`string`	Authorized business context. Never inferred from client record IDs.Format: uuid
`job`Required	path	`string`	Format: uuid

Request

No JSON request body is required.

Example request

Replace synthetic identifiers and credentials. Example dates, coordinates, revisions, and IDs are not production defaults. Read the workflow guide before making a write.

curl --request GET 'https://route-api.okok.space/api/v1/businesses/11111111-1111-4111-8111-111111111111/planning/jobs/11111111-1111-4111-8111-111111111111' \
  --header 'Authorization: Bearer REPLACE_WITH_TOKEN'

Responses

Examples illustrate the documented shape; optional fields and current state can differ. JSON extraction/body-limit errors may be plain text.

200 · Successful response

application/json

Field	Type	Description & constraints
`id`	`string`	Identifier unique within its authorized business. Some create operations generate it when omitted.
`status`	`string`	Current execution or operation state. Planned/unplanned is separate from execution.
`result`	`object \| null`	Resource-specific value; see the related workflow and schema.
`error`	`string \| null`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "id": "example-id",
  "status": "example",
  "result": {
    "routes": [
      {
        "id": "example-id",
        "vehicle_id": "van-01",
        "driver_id": "driver-01",
        "revision": 1,
        "state": "planning",
        "start_at": "2026-11-02T08:00:00Z",
        "end_at": "2026-11-02T16:00:00Z",
        "stops": [
          {}
        ],
        "return_leg": {},
        "warnings": [
          "example"
        ],
        "unplanned_order_ids": [
          "example"
        ],
        "published": {},
        "received_at": "2026-11-02T09:00:00Z"
      }
    ],
    "unplanned": [
      "example"
    ],
    "warnings": [
      "example"
    ]
  },
  "error": "example"
}

Response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "result": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "routes": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Plan"
              }
            },
            "unplanned": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "warnings": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

401 · Missing/invalid/revoked token

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing/invalid/revoked token"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

403 · Business membership or required API-key scope denied

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unauthorized",
    "message": "Business membership or required API-key scope denied"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

404 · Record not found in authorized business

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "not_found",
    "message": "Record not found in authorized business"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

409 · Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "conflict",
    "message": "Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

422 · Domain validation rejected the operation

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "validation",
    "message": "Domain validation rejected the operation"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

503 · Required persistence, map/routing or other infrastructure unavailable

application/json

Field	Type	Description & constraints
`error`Required	`object`	Resource-specific value; see the related workflow and schema.

error fields

Field	Type	Description & constraints
`error.code`Required	`validation \| unauthorized \| not_found \| conflict \| unavailable \| rate_limited`	Private activation or recovery code supplied to the driver.
`error.message`Required	`string`	Resource-specific value; see the related workflow and schema.

Illustrative response

{
  "error": {
    "code": "unavailable",
    "message": "Required persistence, map/routing or other infrastructure unavailable"
  }
}

Response schema

{
  "$ref": "#/components/schemas/Error"
}

← All endpoints Integration workflows →

Read business planning job

Authentication

Parameters

Request

Example request

Responses

200 · Successful response

401 · Missing/invalid/revoked token

403 · Business membership or required API-key scope denied

404 · Record not found in authorized business

409 · Duplicate identifier, stale revision, expired reservation, protected publication or unavailable capacity

422 · Domain validation rejected the operation

503 · Required persistence, map/routing or other infrastructure unavailable