List devices

GET

/api/v1/devices

const url = 'http://localhost:3000/api/v1/devices?limit=20&offset=0&cursor=eyJpZCI6IjEyMzQifQ%3D%3D&status=ONLINE&environment=production&region=us-west&search=edge-01&architecture=amd64&appVersion=1.2.3';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/api/v1/devices?limit=20&offset=0&cursor=eyJpZCI6IjEyMzQifQ%3D%3D&status=ONLINE&environment=production&region=us-west&search=edge-01&architecture=amd64&appVersion=1.2.3' \
  --header 'X-API-Key: <X-API-Key>'

Retrieves a paginated list of devices with optional filtering by status and labels.

Authorizations

api-key
bearer

Parameters

Query Parameters

limit

number

default: 20 >= 1 <= 1000

Example

Maximum number of devices to return

offset

number

Example

Number of devices to skip for pagination

cursor

string

Example

eyJpZCI6IjEyMzQifQ==

Cursor for cursor-based pagination (alternative to offset)

status

string

Allowed values: ONLINE OFFLINE PENDING ERROR

Example

ONLINE

Filter by device status

labels

Filter by device labels (JSON object)

object

key

additional properties

string

Example

{
  "environment": "production",
  "region": "us-west"
}

search

string

Example

edge-01

Free-text search — matches device name, clientId, and Margo self-reported device ID (case-insensitive substring)

architecture

string

Allowed values: amd64 arm64 arm

Example

arm64

Filter by CPU architecture as reported in capabilities.cpu.architecture

appVersion

string

Example

1.2.3

Filter devices that have at least one non-removed deployment of a specific application version

Responses

200

List of devices retrieved successfully

application/json

object

data

required

Array of device objects

Array<object>

object

required

Unique device identifier (UUID)

string format: uuid

clientId

required

Client-provided device identifier

string

name

Human-readable device name

string

status

required

Current device status

string

Allowed values: ONLINE OFFLINE PENDING ERROR

capabilities

required

Device capabilities as reported during onboarding

object

key

additional properties

any

labels

required

Key-value labels for device organization and filtering

object

key

additional properties

string

lastSeenAt

Timestamp of last communication from device

string format: date-time

createdAt

required

Timestamp when device was registered

string format: date-time

updatedAt

required

Timestamp of last device update

string format: date-time

reportedDeviceId

Margo self-reported DeviceId (properties.id from the device capabilities manifest). Unique per organization among non-deleted devices — null if this device has never reported capabilities, or if it collided with another device already holding the same value (FM-1043) and its write was rejected.

string

cpuUsagePercent

Latest reported CPU usage percentage (FM-770, from VictoriaMetrics). Null if the device has never reported telemetry.

number

nullable

memoryUsagePercent

Latest reported memory usage percentage (FM-770, from VictoriaMetrics). Null if the device has never reported telemetry.

number

nullable

diskUsagePercent

Latest reported disk usage percentage (FM-770, from VictoriaMetrics). Null if the device has never reported telemetry.

number

nullable

runningWorkloadCount

Count of non-removed deployment instances currently targeting this device (FM-770). Always a real count, independent of telemetry availability.

number

nullable

total

required

Total number of devices matching the filter criteria

number

hasMore

required

Indicates if there are more devices available

boolean

nextCursor

Cursor for fetching the next page of results

string

Example

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "clientId": "edge-device-001",
      "name": "Production Edge Gateway 1",
      "status": "ONLINE",
      "capabilities": {
        "cpu": {
          "cores": 4,
          "architecture": "arm64"
        },
        "memory": {
          "total": 8192
        },
        "containers": {
          "runtime": "containerd"
        }
      },
      "labels": {
        "environment": "production",
        "region": "us-west",
        "tier": "edge"
      },
      "lastSeenAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "reportedDeviceId": "wm-uc20-m3000-ax4b14pc7500001",
      "cpuUsagePercent": 42.5,
      "memoryUsagePercent": 67.2,
      "diskUsagePercent": 55.1,
      "runningWorkloadCount": 3
    }
  ],
  "total": 150,
  "hasMore": true,
  "nextCursor": "eyJpZCI6IjEyMzQifQ=="
}

401

Unauthorized - Invalid or missing authentication

403

Forbidden - Insufficient permissions