---
title: "Get queued commands to be executed by the physical device."
method: GET
path: "/v2/command-inbox/"
tags: ["commands_Command Status"]
---

# Get queued commands to be executed by the physical device.

`GET /v2/command-inbox/`

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

## Query parameters

- `device_id` string, required

## Response `200`

List of Queued Command Status

- object
  - `code` integer
  - `message` string
  - `content` CommandsCommandInbox
    - `id` string, uuid — Unique command identifier
    - `command` string — The command to be executed
    - `command_args` object — Arguments for the command
      - `script` string — The script to be executed
    - `device_meta` object — Metadata about the device
      - `platform` string — The platform of the device
    - `state` 'Command Queued' — Current state of the command
    - `created_on` string, date-time — Timestamp of command creation
    - `updated_on` string, date-time — Last updated timestamp of command

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