List devices

GET

/api/v1/devices

const url = 'http://localhost:3000/api/v1/devices?limit=20&offset=0&cursor=550e8400-e29b-41d4-a716-446655440000&status=ONLINE&labels=%7B%22environment%22%3A%22production%22%2C%22region%22%3A%22us-west%22%7D&labelKey=environment&unlabeled=true&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=550e8400-e29b-41d4-a716-446655440000&status=ONLINE&labels=%7B%22environment%22%3A%22production%22%2C%22region%22%3A%22us-west%22%7D&labelKey=environment&unlabeled=true&search=edge-01&architecture=amd64&appVersion=1.2.3' \
  --header 'X-API-Key: <X-API-Key>'

Retrieves a paginated list of devices in the caller’s organization. All filters are evaluated server-side and combined with AND: status, labels, labelKey, unlabeled, free-text search (name, clientId, reported device ID, serial number), CPU architecture (Margo rc2 enum) and deployed application version.

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 format: uuid

Example

550e8400-e29b-41d4-a716-446655440000

Cursor for cursor-based pagination (alternative to offset): the nextCursor device ID returned by the previous page

status

string

Allowed values: ONLINE OFFLINE PENDING ERROR

Example

ONLINE

Filter by device status

labels

string

Example

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

Filter by device labels: a JSON-encoded object of exact key/value pairs, all of which must match (AND). Example: {“environment”:“production”,“region”:“us-west”}. 1-20 entries, string values only. Malformed JSON or non-string values are rejected with 400.

labelKey

string

>= 1 characters <= 253 characters

Example

environment

Filter devices that carry this label key, with any value. Combines with labels (AND).

unlabeled

boolean

Example

true

When true, return only devices without any labels. Cannot be combined with labels or labelKey.

search

string

>= 1 characters <= 100 characters

Example

edge-01

Free-text search: case-insensitive substring match on device name, clientId, the Margo self-reported device ID and the Margo-reported serial number. The characters %, _ and backslash match literally.

architecture

string

Allowed values: amd64 arm64 arm

Example

arm64

Filter by CPU architecture as reported by the device in its Margo capabilities (properties.resources.cpu.architecture). Margo rc2 enum.

appVersion

string

>= 1 characters <= 128 characters

Example

1.2.3

Filter devices that have at least one non-removed deployment of this exact application version

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

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

deletionRequestedAt

Set when deletion was requested (FM-1359). The device stays listed while its deployments are withdrawn; it is deleted once the removals are confirmed or time out.

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",
      "deletionRequestedAt": "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=="
}

400

Malformed or contradictory query parameters (for example an architecture outside the Margo rc2 enum, invalid labels JSON, or unlabeled=true combined with labels)

401

Unauthorized - Invalid or missing authentication

403

Forbidden - Insufficient permissions