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

# List Devices

> Retrieve a paginated list of devices, with optional filtering.

Returns a paginated list of devices. Results are automatically scoped to devices you have access to.

## Query parameters

<ParamField query="hardware_ids" type="string[]">
  Filter by hardware IDs. Repeated (`?hardware_ids=id1&hardware_ids=id2`) or comma-separated (`?hardware_ids=id1%2Cid2`). Only `hardware_id` is accepted — filtering by `short_id`
  is not supported.
</ParamField>

<ParamField query="device_type" type="string">
  Filter by device type (e.g. `teebox`, `cartcaddie`).
</ParamField>

<ParamField query="search" type="string">
  Partial match across `name`, `hardware_id`, and `short_id` (case-insensitive).
</ParamField>

<ParamField query="attr_*" type="string">
  Filter by device attribute (e.g. `attr_lock_status=0`).
</ParamField>

<ParamField query="limit" type="number" default="100">
  Max results per page (1–1000).
</ParamField>

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

## Response

<ResponseField name="devices" type="object[]" required>
  Array of device objects.

  <Expandable title="Device object">
    <ResponseField name="short_id" type="string" required>Short, human-friendly device identifier.</ResponseField>
    <ResponseField name="hardware_id" type="string" required>Hardware identifier.</ResponseField>
    <ResponseField name="device_type" type="string" required>Device type (e.g. `teebox`, `cartcaddie`).</ResponseField>
    <ResponseField name="name" type="string">Display name.</ResponseField>
    <ResponseField name="attributes" type="object" required>Latest telemetry attributes (lat, long, battery\_voltage, lock\_status, etc.).</ResponseField>
    <ResponseField name="is_online" type="boolean">Whether the device is currently connected.</ResponseField>
    <ResponseField name="created_at" type="string" required>ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string" required>ISO 8601 last update timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  <Expandable title="Pagination object">
    <ResponseField name="limit" type="number" required>Requested page size.</ResponseField>
    <ResponseField name="offset" type="number" required>Requested offset.</ResponseField>
    <ResponseField name="returned" type="number" required>Number of results in this page. When `returned < limit`, you've reached the last page.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>`bash curl -H "X-API-Key: YOUR_API_KEY" \ "https://your-api-host/devices?device_type=teebox&limit=50" `</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "devices": [
      {
        "short_id": "a1b2c3d4",
        "hardware_id": "ABC123",
        "device_type": "teebox",
        "name": " ",
        "attributes": {
          "lat": 37.7749,
          "long": -122.4194,
          "battery_voltage": 12.4,
          "lock_status": 0
        },
        "is_online": true,
        "created_at": "2025-12-01T00:00:00.000Z",
        "updated_at": "2025-12-17T10:30:00.000Z"
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "returned": 1
    }
  }
  ```
</ResponseExample>