> ## 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.

# List recent commands for a dock

> Returns recent commands on this dock, newest first. The owning organization sees every command on its own hardware, whoever issued it; any other organization entitled to the dock (through a command grant, or the open network) sees only the commands it issued itself. Use it to recover after a lost response: if you sent a command and never received the 202, you hold neither a commandId nor (necessarily) the Idempotency-Key you used, so there is nothing to poll — this answers what was actually issued. `limit` defaults to 5 and is clamped to 20.

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

* **Production:** `GET https://outpost.earthity.com/api/v1/docks/{dockId}/commands`
* **Sandbox:** `GET https://outpost.earthity.com/api/sandbox/v1/docks/{dockId}/commands`
* **Gate:** `credentialed`
* **Read-only:** `true`
* **Destructive:** `false`
* **Idempotent:** `true`

## Parameters

| Name | In | Required | Type | Description |
| - | - | - | - | - |
| `dockId` | path | yes | `string` | Dock id. On the sandbox server this is always `sandbox-dock`. |
| `limit` | query | no | `integer` | How many commands to return, newest first. Out-of-range or unparseable values fall back to the default rather than erroring — this is the endpoint you reach for when something has already gone wrong. |

## Responses

### `200` - Recent commands, newest first.

| Property | Type | Required | Constraints | Description |
| - | - | - | - | - |
| `commands` | `array<object>` | yes | - | |

#### `commands[]`

| Property | Type | Required | Constraints | Description |
| - | - | - | - | - |
| `commandId` | `string` | yes | - | |
| `verb` | `string` | no | enum: open, close | The command that was issued. Omitted in the pathological case where the stored value is outside this enum — the command still appears, because this endpoint exists to help you find a command you lost and hiding it would invite a duplicate actuation, but an unprovable claim about what a door was told to do is not made. |
| `status` | `string` | yes | enum: queued, executing, succeeded, failed, unknown | |
| `outcome` | `string` | no | enum: AT\_ENDSTOP, OBSTRUCTED, TIMEOUT\_FAULT, STOPPED\_LOCAL | Present only once status has left queued/executing. |
| `createdAt` | `string` | yes | format: date-time | |
| `completedAt` | `string` | no | format: date-time | When the command became terminal. For a command swept to `unknown` this is when its result window CLOSED, not when anyone read it — so a days-old timeout can never read as fresh. |
| `source` | `string` | no | enum: local, remote | Where the stroke came from: `local` means a person actuated the dock AT the hardware, `remote` means it was issued through this API. Omitted on a row written before this was recorded, which claims neither. Useful when reconciling: a `local` stroke has no command of yours behind it, so it will never match an Idempotency-Key you sent. |
| `failureReason` | `string` | no | - | Why a command that never actuated did not run (`busy_local`, `busy`, `stopped_local`, `at_limit`, `position_unknown`, ...), or — beside a `STOPPED_LOCAL` outcome — who ended the stroke: `lever_override` (a person took the lever) or `stop_button` (the stop button at the dock). Omitted when the row carries none. The vocabulary may grow without a version bump; treat an unrecognised value as an opaque reason. Same field `dock_command_get` returns (`DockCommandStatus.failureReason`). |

### `401` - Missing or invalid credential.

Body: `application/problem+json` - see [Problem anatomy](/errors#problem-anatomy).

### `404` - Unknown dock, or a dock this credential has no relationship with — the two are deliberately indistinguishable. A 403 here would confirm that a dock id belonging to another tenant is real, which turns this route into an enumeration oracle over other people's hardware.

Body: `application/problem+json` - see [Problem anatomy](/errors#problem-anatomy).

### `429` - Too many reads. Production allows 120 command reads per IP in 10 seconds, and 1,200 per organization in a minute — the organization the read is made for, so a team sharing one office address shares the per-IP allowance but not a quota. A single API key may make at most 600 of those organization reads a minute, half the allowance, so one misbehaving key cannot starve the rest. The sandbox allows 30 reads per IP in 10 seconds. Every one of these 429s carries `Retry-After`; back off until it has passed.

Body: `application/problem+json` - see [Problem anatomy](/errors#problem-anatomy).

### `503` - Fail-closed unavailable: the command-state store, or the rate limiter that meters this read, cannot be reached, so no commands can be listed.

Body: `application/problem+json` - see [Problem anatomy](/errors#problem-anatomy).

## Errors

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


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