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

> Retrieve a paginated list of devices

Retrieve a paginated list of devices in your project, optionally filtered by end user.

## Authentication

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

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

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

  const { data, has_more } = await response.json();
  ```

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

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

  result = response.json()
  devices = result['data']
  ```
</RequestExample>

## Query Parameters

<ParamField query="limit" type="integer" default="25">
  Maximum number of items to return (1-100).
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of items to skip for pagination.
</ParamField>

<ParamField query="end_user_id" type="string">
  Filter devices by bound end user.
</ParamField>

<ParamField query="serial_number" type="string">
  Return the device whose serial number exactly matches this value (1-64 characters). The lookup is scoped to the authenticated project and returns at most one item. When combined with `end_user_id`, this filter takes precedence.
</ParamField>

## Find a Device by Serial Number

Use the `serial_number` filter to recover the Bota device ID (`dev_*`) for a device visible to your project:

```javascript Node.js theme={null}
const targetSerial = 'SN-2025-001234';
const url = new URL('https://api.bota.dev/v1/devices');
url.searchParams.set('serial_number', targetSerial);

const response = await fetch(url, {
  headers: { Authorization: 'Bearer sk_test_...' },
});
const { data } = await response.json();
const device = data[0];

if (device) {
  console.log(device.id);
}
```

Matching is exact and case-sensitive. An empty `data` array means the serial number does not exist or is not accessible to the authenticated project; the API does not reveal which case applies.

If registration returns `409 Conflict`, query this filter. Reuse the returned `dev_*` ID when a match is found. If the result is empty, the device belongs elsewhere or is otherwise inaccessible.

## Response

Returns a paginated list of device objects.

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "dev_abc123",
        "serial_number": "SN-2025-001234",
        "model": "bota_pin",
        "firmware_version": "1.2.3",
        "status": "bound",
        "end_user_id": "eu_xyz789",
        "battery_percent": 85,
        "storage_used_mb": 512,
        "storage_total_mb": 32768,
        "signal_strength_dbm": -75,
        "last_heartbeat_at": "2025-01-15T11:30:00Z",
        "recording_state": {
          "device_state": "idle",
          "pending_recordings": 3,
          "connection_type": ["ble"]
        },
        "metadata": {},
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T11:00:00Z"
      },
      {
        "id": "dev_def456",
        "serial_number": "SN-2025-005678",
        "model": "bota_pin",
        "firmware_version": "1.1.0",
        "status": "unbound",
        "end_user_id": null,
        "battery_percent": null,
        "storage_used_mb": null,
        "storage_total_mb": null,
        "signal_strength_dbm": null,
        "last_heartbeat_at": null,
        "recording_state": null,
        "metadata": {},
        "created_at": "2025-01-14T09:00:00Z",
        "updated_at": "2025-01-14T09:00:00Z"
      }
    ],
    "has_more": false
  }
  ```
</ResponseExample>

## Response Fields

| Field      | Type    | Description                        |
| ---------- | ------- | ---------------------------------- |
| `data`     | array   | List of device objects             |
| `has_more` | boolean | Whether more results are available |

### Device Object

| Field                 | Type            | Description                                                                              |
| --------------------- | --------------- | ---------------------------------------------------------------------------------------- |
| `id`                  | string          | Device identifier (`dev_*`)                                                              |
| `serial_number`       | string          | Physical serial number                                                                   |
| `model`               | string          | Device model (`bota_pin` or `bota_note`)                                                 |
| `firmware_version`    | string \| null  | Current firmware version                                                                 |
| `status`              | string          | `unbound` or `bound`                                                                     |
| `end_user_id`         | string \| null  | Bound end user (`eu_*`), null if unbound                                                 |
| `battery_percent`     | integer \| null | Battery level (0-100), null if no heartbeat received                                     |
| `storage_used_mb`     | integer \| null | Storage used in MB                                                                       |
| `storage_total_mb`    | integer \| null | Total storage capacity in MB                                                             |
| `signal_strength_dbm` | integer \| null | Signal strength in dBm                                                                   |
| `last_heartbeat_at`   | string \| null  | Last heartbeat timestamp (ISO 8601)                                                      |
| `recording_state`     | object \| null  | Current recording state (device\_state, pending\_recordings, flags, connection\_type\[]) |
| `metadata`            | object          | Custom key-value metadata                                                                |
| `created_at`          | string          | Creation timestamp (ISO 8601)                                                            |
| `updated_at`          | string          | Last update timestamp (ISO 8601)                                                         |