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

# Poll a queued command's status/outcome.

> Returns the current status of a previously-queued dock command, and once resolved, its hardware outcome classification. Use this to poll after receiving a 202 from dock_send_command; do not poll faster than once per second, and stop polling once `status` is `succeeded` or `failed`. `outcome` is only present once status leaves `queued`/`executing`. Name approved and reserved 2026-08-03; the sandbox server (see x-sandbox) implements this operation for real — the production route is not yet built.

> **Reserved** — this name is approved and frozen, but the production route is not yet built. A full reference implementation exists in the sandbox — see the `servers` entry and `x-sandbox` extension in the spec.

## `GET /api/v1/docks/{dockId}/commands/{commandId}`

* **Gate:** `session`
* **Read-only:** `true`
* **Destructive:** `false`
* **Idempotent:** `true`

## Parameters

| Name        | In   | Required | Type     | Description                                     |
| ----------- | ---- | -------- | -------- | ----------------------------------------------- |
| `dockId`    | path | yes      | `string` | The dock the command targets.                   |
| `commandId` | path | yes      | `string` | The command id returned by dock\_send\_command. |

## Responses

### `200` — Current command status.

| Property    | Type     | Required | Constraints                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------- | -------- | -------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commandId` | `string` | no       | —                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `status`    | `string` | no       | enum: queued, executing, succeeded, failed               | Open set — clients must tolerate additional values added in the future without a version bump. `queued` and `executing` are non-terminal and carry no `outcome`; `succeeded` and `failed` are terminal and always carry one.                                                                                                                                                                                                                                                                        |
| `outcome`   | `string` | no       | enum: KICK, RUN, AT\_ENDSTOP, OBSTRUCTED, TIMEOUT\_FAULT | Pico hardware classification of how an actuation resolved. Open set — clients must tolerate additional values added in the future without a version bump. The terminal `status` is determined by the outcome and is not independently chosen: KICK, RUN and AT\_ENDSTOP resolve as `succeeded`; OBSTRUCTED and TIMEOUT\_FAULT resolve as `failed`. (Reporting a jammed door as `succeeded` is a contract violation, not an implementation choice — the shared contract suite asserts this pairing.) |

### `401` — Not signed in.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `403` — The caller lacks entitlement on this dock.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `404` — No such command (or dock).

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `429` — Too many requests from this IP.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

### `503` — The command-state store is fail-closed unavailable, so no command status can be read.

| Property            | Type      | Required | Constraints           | Description                                                                                                                                                                                                       |
| ------------------- | --------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`              | `string`  | yes      | format: uri-reference |                                                                                                                                                                                                                   |
| `status`            | `integer` | yes      | —                     |                                                                                                                                                                                                                   |
| `title`             | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `detail`            | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `instance`          | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `code`              | `string`  | yes      | —                     |                                                                                                                                                                                                                   |
| `field`             | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `error`             | `string`  | no       | —                     | Legacy-compat mirror of `detail` (or `title` when no `detail` is given), added by apiProblemResponse (lib/problem.ts) so pre-C2 consumers reading `.error` off a live route's error body keep working unmodified. |
| `documentation_url` | `string`  | no       | —                     |                                                                                                                                                                                                                   |
| `request_id`        | `string`  | no       | —                     |                                                                                                                                                                                                                   |

## Errors

* [unauthorized](/errors/unauthorized)
* [forbidden](/errors/forbidden)
* [not\_found](/errors/not_found)
* [rate\_limited](/errors/rate_limited)
* [command\_unavailable](/errors/command_unavailable)