# List Devices

> Fleets API · Devices

```http
GET https://app.mk.io/api/v1/projects/{project_name}/fleet/devices
```

List devices on the specified project. To learn more about devices, read [Device Concept](ref:fleet-api#device-concept).

## Listing, Sorting and Filtering Devices

This endpoint returns the list of devices in the specified project.

### Sorting

The results from this endpoint can be ordered using the `$orderby` query parameter. Specify a list of field names, separated by commas
where each one can optionally specify `asc` or `desc`.

Sorting is valid on the following fields: `created`, `createdBy`, `displayName`, `id`, `labels`, `metadata/created`, `metadata/displayName`, `metadata/name`, `name`, `status/alarmSeverity`, `status/beamHA/activeControllerDeviceName`, `status/beamHA/roles`, `status/currentSoftwareVersion`, `status/lastContact`, `status/model`, `status/rollbackSoftwareVersion`, `status/serialNumber`, `updated`, `updatedBy`

### Filtering

There are two ways to filter the set of returned devices from this endpoint - the first is to use the `$filter` query parameter, the second is to use the
`$label_key` and `$label` query parameters.

The `$filter` query parameter allows for devices to be filtered on the basis of fields in the schema using OData query syntax.
See [this document](https://learn.microsoft.com/en-us/odata/concepts/queryoptions-overview#filter) for more details on the syntax used.

Filters are valid on the following fields: `created`, `createdBy`, `createdByEmail`, `createdByName`, `displayName`, `id`, `labels`, `metadata/created`, `metadata/displayName`, `metadata/name`, `name`, `spec/siteName`, `status/alarmSeverity`, `status/beamHA/activeControllerDeviceName`, `status/beamHA/roles`, `status/currentSoftwareVersion`, `status/lastContact`, `status/model`, `status/rollbackSoftwareVersion`, `status/serialNumber`, `updated`, `updatedBy`, `updatedByEmail`, `updatedByName`

`$label_key` and `$label` are specific to querying devices based on their labels. Labels are a set of key-value pairs that can be used to identify devices with
any arbitrary metadata you want, specifically for the purpose of retrieving relevant subsets of devices.

### Examples:

`?$top=10` - Returns only the first 10 devices from the list.

`?$orderby=name desc` - Sorts devices by name in descending order.

`?$filter=name eq 'descriptive name'` - Returns devices that match the provided name.

`?$orderby=created desc` - Sorts devices by creation date in descending order.

`?$filter=created ge 2021-01-01T00:00:00Z` - Returns devices created after January 1, 2021.

`?$label=studio=paravalley` - Returns devices with the label `studio` set to `paravalley`.

`?$label=release-date~2023` - Returns devices with the label `release-date` set to a value that contains `2023`.

`?$label_key=studio&label_key=release-date` - Returns devices with any value set for the `studio` label and the `release-date` label.

RBAC Capability Required: `fleet.device.get`

## Authentication

- `Authorization` header — Bearer authentication of the form `Bearer <token>`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `project_name` | string | Yes | — |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `$orderby` | string | No | Specifies the key by which the result collection should be ordered. |
| `$filter` | string | No | Restricts the set of items returned. |
| `$top` | string | No | Specifies a non-negative integer `n` that limits the number of items returned from a collection. The service returns the number of available items up to but not greater than the specified value `n`. |
| `$skiptoken` | string | No | Specifies a start offset to support paginated results. Use `@odata.nextLink` in the result object to enumerate the collection - it will be present only if there's more than one page of entities. |
| `$label_key` | string | No | Filters the set to the specified label key. If multiple $label_keys are specified, matching items must have all labels. |
| `$label` | string | No | Filters the set to the specified label key/value pair. Supports equality, inequality, and inexact matching. If multiple values are provided for the same key, items matching either value will be returned. |

## Example request

```bash
curl -X GET "https://app.mk.io/api/v1/projects/{project_name}/fleet/devices" \
  -H "Authorization: Bearer <token>"
```

## Responses

### 200 — A list of devices

- `@odata.nextLink` · string · Optional — @odata.nextLink URL if the page length and number of items match.
- `supplemental` · object · **Required** — Supplemental info
  - `count` · integer · **Required** — Number of items returned
  - `kind` · string · **Required** — Type of items in the list
  - `operation` · string · **Required** — Operation type. Should always say 'list'
  - `pagination` · object · **Required** — Pagination info
    - `end` · integer · **Required** — Position of the last item in the list
    - `records` · integer · **Required** — Total number of items returned in the list
    - `start` · integer · **Required** — Position of the first item in the list
    - `total` · integer · **Required** — Total number of items in the project
  - `subscription` · object · Optional — Project info
    - `id` · string · **Required** — Project ID
    - `name` · string · **Required** — Project name
- `value` · list of objects · **Required** — A list of devices.
  - Array items (object):
    - `kind` · string · **Required** — The kind of record.
    - `metadata` · object · **Required** — Device metadata.
      - `created` · string · Optional · _format: date-time_ — The time when the resource was created
      - `createdBy` · string · Optional · _format: uuid_ — ID of the user who created the resource
      - `createdByEmail` · string · Optional — Email of the user who created the resource
      - `displayName` · string · Optional — The display name of the resource
      - `id` · string · **Required** · _format: uuid_ — The ID of the resource
      - `labels` · map from strings to string · Optional — A dictionary of labels associated with the resource
        - `[any key]` · string — map of additional properties
      - `name` · string · Optional — The name of the resource
      - `updated` · string · Optional · _format: date-time_ — The time when the resource was last updated
      - `updatedBy` · string · Optional · _format: uuid_ — ID of the user who last updated the resource
      - `updatedByEmail` · string · Optional — Email of the user who last updated the resource
    - `spec` · object · **Required** — Device specification.
      - `autoPreloadLatestSoftware` · boolean · Optional · _Defaults to false_ — Whether the device should automatically preload the latest available software version.
      - `availableNetworks` · list of objects · **Required** — The list of <<glossary:network>>s available to the device and, optionally, the interfaces they are connected to. Leave the available networks list empty to give the device access to all of the networks with routes to the device's <<glossary:site>>. Read [Available networks](ref:fleet-api#available-networks) to learn more.
        - Array items (object):
          - `interfaceName` · string · **Required** · _pattern: [^\s\/]{1,16}_ — The name of the <<glossary:device interface>> that will be connected to the network.
          - `networkName` · string · **Required** · _pattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$_ — The name of the <<glossary:network>> that will be made available to this device.
      - `desiredSoftwareVersion` · string · Optional · _<=255 characters_ — The desired version of software that should be running on the device.
      - `geolocation` · object · Optional — Optional geolocation data for the device.
        - `coordinates` · list of doubles · **Required** · _0-2 items_ — Co-ordinates that describe the geolocation (ISO 6709), an array of two floating point numbers [latitude(North - South), longitude(East - West)]. Set an empty array to clear the geolocation.
          - Array items (double):
      - `locationId` · string · Optional · _pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$_ — The location id is the identity of the actual device that will be associated with this record. This can be used instead of the `shortCode` field when registering an on-prem device. The location id does not change so this can be a simpler approach for large scale system administration.
      - `preloadSoftwareVersion` · string · Optional · _<=255 characters_ — A version of the software that should be preloaded on the device.
      - `shortCode` · string · Optional · _8-8 characters_ — The short code from a device's web user interface, used to on-board the device. The short code expires quickly, so it should be used immediately after it is generated. Read [On-board fleet devices](doc:on-board-fleet-devices) to learn more about on-boarding devices.
      - `siteName` · string · Optional · _pattern: ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$_ — The name of the <<glossary:site>> where the device is located.
    - `status` · object · **Required** — Device status.
      - `alarmSeverity` · enum · Optional — The most severe alarm level last reported by the device. - 0 - Clear - 1 - Info - 2 - Warning - 3 - Error - 4 - Critical
        - Allowed values: `0`, `1`, `2`, `3`, `4`
      - `assignedFlows` · list of objects · Optional — The a list of the <<glossary:flow>> names assigned to the device.
        - Array items (object):
          - `name` · string · **Required** · _pattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$_ — The name of a <<glossary:flow>> assigned to the device.
      - `beamHA` · object · Optional — Information about the beamHA the device is connected to.
        - `activeControllerDeviceName` · string · Optional · _1-64 characters_ — The name of the active controller device in the beamHA.
        - `roles` · list of strings · **Required** · _0-3 items_ — The roles of the device in the beamHA (high availability) group.
          - Array items (string):
        - `status` · string · Optional — The status of the beamHA group. Only returned for the active controller device.
        - `unregisteredDevices` · list of strings · Optional — List of location IDs of devices that are part of the beamHA but not registered. Only returned for the active controller device.
          - Array items (string):
      - `capabilities` · object · Optional — Device capabilities based on software version and hardware.
        - `configurationBackup` · boolean · Optional — Whether the device supports configuration backup. Returns false for devices with beam software version older than 1.6.
      - `currentSoftwareVersion` · string or null · Optional · _<=255 characters_ — The current software version running on the device, as reported by the device.
      - `geolocation` · object · Optional — Optional geolocation data for the device.
        - `coordinates` · list of doubles · **Required** · _0-2 items_ — Co-ordinates that describe the geolocation (ISO 6709), an array of two floating point numbers [latitude(North - South), longitude(East - West)]. Set an empty array to clear the geolocation.
          - Array items (double):
      - `interfaces` · list of objects · Optional — A list of the physical and virtual interfaces reported by the device. If an interface is referenced directly by a source or a destination, it may be continue to be present in the list even if the device no longer reports it. The `state` field indicates if the interface is currently present on the device.
        - Array items (object):
          - `ipAddresses` · list of strings · Optional — The IP address associated with this interface, if applicable.
            - Array items (string):
          - `name` · string · **Required** · _pattern: ^([^\s\/]{1,16}|[a-zA-Z][a-zA-Z0-9_]{1,255})$_ — The name of the interface on the device.
          - `state` · enum · **Required** — Whether the interface is currently present on the device. If an interface is referenced directly by a source or a destination, it may be continue to be present in the list even if the device no longer reports it.
            - Allowed values: `NotPresent`, `Present`
          - `type` · enum · **Required** — The type of the physical or virtual interface on the device (IP, SDI/ASI or RF).
            - Allowed values: `IP`, `SDIASI`, `RF`
      - `lastContact` · string or null · Optional — The last time the device contacted the system.
      - `locationId` · string or null · Optional · _pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$_ — The location id is the identity of the actual device that will be associated with this record. This can be used instead of the `shortCode` field when registering an on-prem device. The location id does not change so this can be a simpler approach for large scale system administration.
      - `preloadedSoftware` · list of objects or null · Optional — The preloaded software present on the device.
        - Array items (object):
          - `downgradeCompatible` · boolean · Optional — Whether switching to this release is safe from an underlying component perspective. False if this release has a lower minimum version requirement than the currently installed release. True when no suitable reference release can be found (fail open).
          - `name` · string · **Required** · _1-255 characters_ — The name of the preloaded software present on the device.
          - `precentProgress` · integer · Optional · _0 to 100_ — Indication of coarse progress for states with a significant duration.
          - `progressDetails` · string · Optional · _<=255 characters_ · _Defaults to _ — Additional information about states with a significant duration.
          - `state` · enum · **Required** — The current state of the preloaded software.
            - Allowed values: `Requested`, `Downloading`, `Downloaded`, `Importing`, `PreloadFailed`, `PreloadCancelled`, `Removing`, `Removed`
          - `upgradeCompatible` · boolean · Optional — Whether the device's current software version meets the minimum version requirement for upgrading to this release. Mirrors the field on the device software list endpoint.
          - `version` · string · **Required** · _<=255 characters_ — The version of the preloaded software.
      - `rollbackSoftwareVersion` · string or null · Optional · _<=255 characters_ — The rollback software version, as reported by the device.
      - `secondsSinceLastContact` · integer or null · Optional — The number of seconds since the last time the device contacted the system.
      - `serialNumber` · string or null · Optional · _1-255 characters_ — The serial number of the device, as reported by the device.
      - `softwareName` · string or null · Optional · _0-255 characters_ — The name of the software installed on the device.
      - `softwareUpgradeState` · enum · Optional — Indicates if a software upgrade is in progress or has failed.
        - Allowed values: `Idle`, `Switching`, `SwitchFailed`
      - `url` · string · Optional · _1-2048 characters_ — The URL to access the device's web interface remotely.

Example:

```json
{
  "@odata.nextLink": "string",
  "supplemental": {
    "count": 0,
    "kind": "string",
    "operation": "string",
    "pagination": {
      "end": 0,
      "records": 0,
      "start": 0,
      "total": 0
    },
    "subscription": {
      "id": "string",
      "name": "string"
    }
  },
  "value": [
    {
      "kind": "string",
      "metadata": {
        "created": "2024-01-01T00:00:00Z",
        "createdBy": "00000000-0000-0000-0000-000000000000",
        "createdByEmail": "string",
        "displayName": "string",
        "id": "00000000-0000-0000-0000-000000000000",
        "labels": {
          "label1": "value1",
          "label2": "value2"
        },
        "name": "string",
        "updated": "2024-01-01T00:00:00Z",
        "updatedBy": "00000000-0000-0000-0000-000000000000",
        "updatedByEmail": "string"
      },
      "spec": {
        "autoPreloadLatestSoftware": true,
        "availableNetworks": [
          {
            "interfaceName": "eth0",
            "networkName": "internet"
          }
        ],
        "desiredSoftwareVersion": "1.0.0.0",
        "geolocation": {
          "coordinates": [
            0
          ]
        },
        "locationId": "e188ca13-604f-4940-9afb-c3cb952baf01",
        "preloadSoftwareVersion": "1.0.0.1",
        "shortCode": "XU7U23WD",
        "siteName": "world"
      },
      "status": {
        "alarmSeverity": 0,
        "assignedFlows": [
          {
            "name": "channel-1"
          }
        ],
        "beamHA": {
          "activeControllerDeviceName": "controller-01",
          "roles": [
            "Controller",
            "Worker",
            "Arbiter"
          ],
          "status": "OK",
          "unregisteredDevices": [
            "e188ca13-604f-4940-9afb-c3cb952baf01"
          ]
        },
        "capabilities": {
          "configurationBackup": true
        },
        "currentSoftwareVersion": "1.0.0.2",
        "geolocation": {
          "coordinates": [
            0
          ]
        },
        "interfaces": [
          {
            "ipAddresses": [
              "10.10.10.1"
            ],
            "name": "eth0",
            "state": "Present",
            "type": "IP"
          }
        ],
        "lastContact": "string",
        "locationId": "e188ca13-604f-4940-9afb-c3cb952baf01",
        "preloadedSoftware": [
          {
            "downgradeCompatible": true,
            "name": "beam",
            "precentProgress": 25,
            "progressDetails": "1.2GiB of 4.9GiB",
            "state": "Downloading",
            "upgradeCompatible": true,
            "version": "1.0.0.0"
          }
        ],
        "rollbackSoftwareVersion": "1.0.0.1",
        "secondsSinceLastContact": 0,
        "serialNumber": "string",
        "softwareName": "beam",
        "softwareUpgradeState": "Idle",
        "url": "string"
      }
    }
  ]
}
```

### 400 — Bad Request

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 401 — Unauthorized

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 403 — Forbidden

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 404 — Not Found

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 429 — Too Many Requests

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 500 — Internal Server Error

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

---

Source spec: `fleets-api` · operationId: `[get]_/api/v1/projects/{project_name}/fleet/devices`