Skip to main content
GET
/
devices
/
{id}
/
commands
curl "https://api.bota.dev/v1/devices/dev_abc123/commands" \
  -H "Authorization: Bearer sk_live_..."

{
  "data": [
    {
      "id": "cmd_xyz789",
      "device_id": "dev_abc123",
      "type": "start_recording",
      "status": "executed",
      "params": {
        "max_duration_sec": 3600,
        "upload_immediately": true
      },
      "grant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "result": {
        "recording_id": "rec_def456",
        "started_at": "2025-01-20T10:55:30Z"
      },
      "error": null,
      "expires_at": "2025-01-20T11:00:00Z",
      "delivered_at": "2025-01-20T10:55:15Z",
      "executed_at": "2025-01-20T10:55:30Z",
      "created_at": "2025-01-20T10:55:00Z"
    },
    {
      "id": "cmd_abc123",
      "device_id": "dev_abc123",
      "type": "stop_recording",
      "status": "pending",
      "params": {},
      "grant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "result": null,
      "error": null,
      "expires_at": "2025-01-20T12:00:00Z",
      "delivered_at": null,
      "executed_at": null,
      "created_at": "2025-01-20T11:55:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
List commands sent to a device, optionally filtered by status.

​
Authentication

Requires an API key with devices:read scope. 
curl "https://api.bota.dev/v1/devices/dev_abc123/commands" \
  -H "Authorization: Bearer sk_live_..."

​
Path Parameters

​
id
string
required
The device’s unique identifier (e.g., dev_abc123).

​
Query Parameters

​
status
string
Filter by command status. One of: pending, delivered, executed, failed, expired, cancelled.
​
limit
number
Maximum number of results to return (1-100). Default: 20.
​
cursor
string
Cursor for pagination.

​
Response

Returns a paginated list of command objects. 
{
  "data": [
    {
      "id": "cmd_xyz789",
      "device_id": "dev_abc123",
      "type": "start_recording",
      "status": "executed",
      "params": {
        "max_duration_sec": 3600,
        "upload_immediately": true
      },
      "grant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "result": {
        "recording_id": "rec_def456",
        "started_at": "2025-01-20T10:55:30Z"
      },
      "error": null,
      "expires_at": "2025-01-20T11:00:00Z",
      "delivered_at": "2025-01-20T10:55:15Z",
      "executed_at": "2025-01-20T10:55:30Z",
      "created_at": "2025-01-20T10:55:00Z"
    },
    {
      "id": "cmd_abc123",
      "device_id": "dev_abc123",
      "type": "stop_recording",
      "status": "pending",
      "params": {},
      "grant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "result": null,
      "error": null,
      "expires_at": "2025-01-20T12:00:00Z",
      "delivered_at": null,
      "executed_at": null,
      "created_at": "2025-01-20T11:55:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

​
Response Fields

FieldTypeDescription
idstringThe command’s unique identifier
device_idstringThe target device ID
typestringCommand type: start_recording or stop_recording
statusstringCurrent status of the command
paramsobjectCommand parameters
grant_tokenstringSigned JWT authorizing command execution
resultobjectExecution result (if executed)
errorobjectError details (if failed)
expires_atstringWhen the command expires
delivered_atstringWhen the command was delivered to device
executed_atstringWhen the command was executed
created_atstringWhen the command was created