> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bota.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List Recording Commands

> List all recording commands for a device

List commands sent to a device, optionally filtered by status.

## Authentication

Requires an [API key](/authentication) with `devices:read` scope.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.bota.dev/v1/devices/dev_abc123/commands" \
    -H "Authorization: Bearer sk_live_..."
  ```

  ```bash cURL (Pending Only) theme={null}
  curl "https://api.bota.dev/v1/devices/dev_abc123/commands?status=pending" \
    -H "Authorization: Bearer sk_live_..."
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.bota.dev/v1/devices/dev_abc123/commands', {
    headers: {
      'Authorization': 'Bearer sk_live_...',
    },
  });

  const commands = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.bota.dev/v1/devices/dev_abc123/commands',
      headers={'Authorization': 'Bearer sk_live_...'},
  )

  commands = response.json()
  ```
</RequestExample>

## Path Parameters

<ParamField path="id" type="string" required>
  The device's unique identifier (e.g., `dev_abc123`).
</ParamField>

## Query Parameters

<ParamField query="status" type="string">
  Filter by command status. One of: `pending`, `delivered`, `executed`, `failed`, `expired`, `cancelled`.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of results to return (1-100). Default: 20.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for pagination.
</ParamField>

## Response

Returns a paginated list of command objects.

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "not_found",
      "message": "Device not found"
    }
  }
  ```
</ResponseExample>

## Response Fields

| Field          | Type   | Description                                         |
| -------------- | ------ | --------------------------------------------------- |
| `id`           | string | The command's unique identifier                     |
| `device_id`    | string | The target device ID                                |
| `type`         | string | Command type: `start_recording` or `stop_recording` |
| `status`       | string | Current status of the command                       |
| `params`       | object | Command parameters                                  |
| `grant_token`  | string | Signed JWT authorizing command execution            |
| `result`       | object | Execution result (if executed)                      |
| `error`        | object | Error details (if failed)                           |
| `expires_at`   | string | When the command expires                            |
| `delivered_at` | string | When the command was delivered to device            |
| `executed_at`  | string | When the command was executed                       |
| `created_at`   | string | When the command was created                        |