get status list for command request

⚠️ Android only. This endpoint applies to command requests issued to Android-managed devices.

Alternative Available

A newer, multi-OS commands API is available and recommended for most use cases https://api.esper.io/openapi/command-request/listcommandrequests

Returns the per-device execution status for a specific command request, with optional filtering by device or command state. Returns a paginated list of V0CommandStatus1 records — one per targeted device — each showing the device reference, current execution state, reason, and timestamps. Use this to monitor command propagation after creating a request via POST .../command/.

About Get Command Request Status

When a command request is created, Esper generates a per-device status record for each target in the request. This endpoint surfaces those records, allowing integrators to track whether each device has queued, acknowledged, completed, failed, timed out, or been cancelled. The state field reflects the full command lifecycle from Command Queued through Command Success or Command Failure. The reason field provides detail on why a command reached its current state — useful for diagnosing failures.

Key Fields / Query Parameters

request_id — path parameter; UUID of the command request whose status to retrieve.

device — optional query filter; narrows results to a single device UUID.

state — optional query filter; narrows results to a specific execution state (e.g. Command Failure, Command Success).

state values: Command Queued, Command Initiated, Command Acknowledged, Command In Progress, Command TimeOut, Command Success , Command Failure, Command Scheduled, Command Cancelled.

reason — plain-language explanation of why the command is in its current state.

Common Use Cases

Monitor rollout progress for a group-scoped install command by checking how many devices have reached Command Success. Identify devices that failed or timed out by filtering on state=Command Failure or state=Command TimeOut. Note: timeout status will continue to scuees or failur. Confirm that a specific device received and acknowledged a command before proceeding with a dependent operation.

Best Practices

Poll this endpoint periodically after creating a command request rather than expecting immediate completion — devices may be offline or slow to respond Filter by state=Command Failure first to quickly surface problem devices before reviewing overall progress Store request_id from the create response immediately — it cannot be recovered from the status endpoint itself

Workflow

After creating a command request, capture the request_id from the POST response. Call this endpoint with the request_id to retrieve per-device status records. Filter by state to isolate devices in specific execution states; retry or investigate failures as needed.