---
title: "get command history for device"
method: GET
path: "/v0/enterprise/{enterprise_id}/device/{device_id}/command-history/"
tags: ["esper_cloud_api_Commands V2"]
---

# get command history for device

`GET /v0/enterprise/{enterprise_id}/device/{device_id}/command-history/`

⚠️ Android only. This endpoint applies exclusively to Android-managed devices enrolled in Esper.

**Alternative Available**

Use https://api.esper.io/openapi/command-status/getcommandinbox for a device's queued commands.

Returns the full command history for a specific device, filterable by execution state.

Returns a paginated list of V0CommandStatus records scoped to the specified device, each including the command name, arguments, issuing user, current state, reason, requeue count, and timestamps. 

This provides richer detail than the per-request status endpoint, making it the preferred choice for device-level command audit and troubleshooting.

**About Device Command History**

While GET .../command/{request_id}/status/ surfaces status for a specific command request across its target devices, the command-history endpoint inverts the view — returning all commands ever 
issued to a single device, regardless of which request they originated from. Each record includes the full command name, the command_args used, the issued_by user object, a requeue_value tracking how many times the command was retried, and the reason for the current state. This makes it the authoritative source for per-device command forensics.

**Key Query Parameters / Fields**

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

command — the name of the operation that was issued (e.g. INSTALL, REBOOT)

command_args — the arguments passed with the command

issued_by — object containing id and username of the user who issued the command

requeue_value — number of times the command was requeued for this device 

reason — plain-language detail on why the command is in its current state

**Common Use Cases**

Review the full command history for a device during a support or compliance investigation.

Identify repeatedly failing commands and the arguments that were used.
Audit which users issued which commands to a device over its lifecycle.

**Best Practices**

Filter by state=Command Failure or state=Command TimeOut to surface problem commands without reviewing the entire history.

Use requeue_value to identify commands that were retried the maximum number of times — these are likely permanent failures requiring manual intervention.

Pair this endpoint with the event feed (GET .../report/eventfeed/) for a complete device activity picture: command history shows operational commands; the event feed shows broader device state transitions.

**Workflow**

Obtain the device_id from a device list call or stored reference.

Call this endpoint, optionally filtering by state, to retrieve the command history.

Investigate failures using the command, command_args, reason, and requeue_value fields.

## Path parameters

- `enterprise_id` string, uuid, required
- `device_id` string, uuid, required

## Query parameters

- `state` string

## Response `200`

on successful request

- object
  - `count` integer
  - `next` string, url
  - `previous` string, url
  - `results` EsperCloudApiV0CommandStatus[]
    - `id` string, uuid — Unique command identifier
    - `request` string, uuid — Request Id associated with this command
    - `command` string
    - `command_args` object — arguments in command
    - `issued_by` object
      - `id` integer
      - `username` string
    - `device` string, url — 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
    - `requeue_value` integer — indicates the command's requeue count for the device, which is limited to a maximum of 3 retries.
    - `created_on` string, date-time — Timestamp of command creation
    - `updated_on` string, date-time — Last updated timestamp of command

## Other responses

- `401` — Authorization information is missing or invalid.
- `404` — Not Found.
- `500` — Internal server error

---

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