Retrieves the commands currently queued for a specific device to execute.

This is the device-facing endpoint the Esper agent itself calls to pick up its pending work; it returns commands in the Command Queued state for the given device_id, along with the command arguments and basic device metadata.

About Command Inbox

While GET /commands/v0/status/ gives an administrative view of command execution across the tenant, the command inbox is the device-side queue that the Esper agent polls to find out what it needs to run next. It is scoped to a single device_id and reflects only commands that have not yet been picked up.

Key Fields / Query Parameters

device_id — the device whose queued commands should be returned, required

Common Use Cases

Verifying that a command was actually queued for delivery to a specific device

Diagnosing a device that isn't executing commands by checking whether they are reaching its inbox at all

Best Practices

If a command doesn't appear here after being issued, check the device's connectivity and last-seen time before assuming the command failed to queue

Use this alongside GET /commands/v0/status/{id}/ to distinguish between a command that never reached the device and one that reached it but failed to execute

Workflow

Issue a command targeting the device through POST /commands/v0/commands/

Call this endpoint with the device_id to confirm the command is queued

If the command doesn't appear, check the device's last-seen status before retrying