---
title: "Update command status"
method: PUT
path: "/commands/v0/status/{id}/"
tags: ["commands_Command Status"]
---

# Update command status

`PUT /commands/v0/status/{id}/`

Updates the state of an individual command status record. Supports only CANCEL. Cancellations are not always guaranteed and depends on the command's exact state.

**About Update Command Status**

Each CommandStatus record tracks the execution of one command against one device and is created automatically when a command request targets that device. This endpoint lets you override the current lifecycle state directly rather than waiting for the device to report back. It's typically used by internal tooling and integrations that need to reconcile command state (such as cancelling a command stuck in Command Queued) rather than as part of a normal command-issuing workflow.

**Key Fields / Request Body**

state — the new command state; accepts Command Cancelled

reason — free text explaining why the state was changed

**Common Use Cases**

Cancelling a command that is stuck in a queued state before it reaches the device

Forcing a command into a terminal state when a device is known to be offline or decommissioned


**Best Practices**

Use GET /commands/v0/status/{id}/ first to confirm the command's current state before changing it

Always include a reason so the change is auditable in the command history

Prefer letting the device report its own status through the normal command lifecycle; only override manually when necessary

**Workflow**

Call GET /commands/v0/status/{id}/ to review the command's current state and device

Determine the correct terminal or intermediate state to apply

PUT the new state and reason to this endpoint

Confirm the update by re-fetching the command status record

## Path parameters

- `id` string, required

## Request body

- CommandsCommandStatusPUT
  - `state` 'Command Acknowledged' | 'Command In Progress' | 'Command TimeOut' | 'Command Success' | 'Command Failure' | 'Command Scheduled' | 'Command Cancelled' — Command state to update
  - `reason` string — State change reason to update

## Response `200`

Command status successfully updated.

- object
  - `code` integer
  - `message` string
  - `content` CommandsCommandStatus
    - `id` string, uuid — Unique command identifier
    - `request` string, uuid — Request Id associated with this command
    - `device` string, uuid — Device associated with this command
    - `state` 'Command Queued' | 'Command Initiated' | 'Command Acknowledged' | 'Command In Progress' | 'Command TimeOut' | 'Command Success' | 'Command Failure' | 'Command Scheduled' | 'Command Cancelled' — Current state of the command
    - `reason` string — details briefing the reason for current command state
    - `created_at` string, date-time — Timestamp of command creation
    - `updated_at` string, date-time — Last updated timestamp of command
    - `command_meta` object, nullable — Optional metadata associated with the command execution result. Present only for commands that return structured data from the device.
      - `result` unknown

## Other responses

- `400` — Bad request
- `401` — Authorization information is missing or invalid.
- `500` — Internal server error

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/revisions/e1f64cbb488e/schema)