> For the complete documentation index, see [llms.txt](https://docs.balena.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balena.io/reference/api/resources/device.md).

# Device

## Available Fields

| Field                                  |
| -------------------------------------- |
| `id`                                   |
| `belongs_to__application`              |
| `belongs_to__user`                     |
| `actor`                                |
| `device_name`                          |
| `is_of__device_type`                   |
| `uuid`                                 |
| `is_running__release`                  |
| `is_pinned_on__release`                |
| `should_be_running__release`           |
| `note`                                 |
| `local_id`                             |
| `status`                               |
| `overall_status`                       |
| `is_online`                            |
| `last_connectivity_event`              |
| `is_connected_to_vpn`                  |
| `last_vpn_event`                       |
| `ip_address`                           |
| `mac_address`                          |
| `public_address`                       |
| `os_version`                           |
| `os_variant`                           |
| `should_be_operated_by__release`       |
| `supervisor_version`                   |
| `should_be_managed_by__release`        |
| `is_managed_by__service_instance`      |
| `provisioning_progress`                |
| `provisioning_state`                   |
| `download_progress`                    |
| `is_web_accessible`                    |
| `longitude`                            |
| `latitude`                             |
| `location`                             |
| `custom_longitude`                     |
| `custom_latitude`                      |
| `is_locked_until__date`                |
| `is_accessible_by_support_until__date` |
| `created_at`                           |
| `is_active`                            |
| `api_heartbeat_state`                  |
| `memory_usage`                         |
| `memory_total`                         |
| `storage_block_device`                 |
| `storage_usage`                        |
| `storage_total`                        |
| `cpu_temp`                             |
| `cpu_usage`                            |
| `cpu_id`                               |
| `is_undervolted`                       |

***

## Examples

### Get all devices by fleet

```bash
GET "https://api.balena-cloud.com/v7/device?\$filter=belongs_to__application%20eq%20'<FLEET ID>'" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Get all devices by organization

```bash
GET "https://api.balena-cloud.com/v7/device?\$filter=belongs_to__application/any(a:a/organization%20eq%20'<ORG ID>')" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Get device by ID

```bash
GET "https://api.balena-cloud.com/v7/device(<ID>)" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Get device by UUID

```bash
GET "https://api.balena-cloud.com/v7/device(uuid='<UUID>')" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Get multiple devices by UUID

```bash
GET "https://api.balena-cloud.com/v7/device?\$filter=uuid%20in%20(%27<UUID1>%27,%27<UUID2>%27,%27<UUID3>%27)" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Get the device overall\_status field

The overall\_status field is returned only when explicitly requested with $select.

```bash
GET "https://api.balena-cloud.com/v7/device(<ID>)?\$select=overall_status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Get the release currently running on a device

```bash
GET "https://api.balena-cloud.com/v7/device(<ID>)?\$select=is_running__release" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Get the release a device is pinned to

Note: is\_pinned\_on\_\_release will be null/not set if the device isn't pinned to any release, in which case the device will be tracking the release of the application it belongs to.

```bash
GET "https://api.balena-cloud.com/v7/device(<ID>)?\$select=is_pinned_on__release" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Pin device to a specific release by ID

```bash
PATCH "https://api.balena-cloud.com/v7/device(<ID>)" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "is_pinned_on__release": <RELEASE ID>
}'
```

### Pin device to a specific release by UUID

```bash
PATCH "https://api.balena-cloud.com/v7/device(uuid='<UUID>')" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "is_pinned_on__release": <RELEASE ID>
}'
```

### Get the target release of a device

This will be the release that the device is pinned to, or the target release of the fleet for non-pinned devices.

```bash
GET "https://api.balena-cloud.com/v7/device(uuid='<UUID>')?\$select=should_be_running__release" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Mark a device to be updated to a specific supervisor release

To request a list of available supervisor releases, check the 'List Supervisor releases' documentation page.

```bash
PATCH "https://api.balena-cloud.com/v7/device(uuid='<UUID>')" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "should_be_managed_by__release": <SUPERVISOR RELEASE ID>
}'
```

### Mark a device to be updated to a specific OS release

This endpoint relies on the Experimental Queued OS updates feature. To request a list of available OS releases, check the 'List balenaOS releases' documentation page.

```bash
PATCH "https://api.balena-cloud.com/v7/device(uuid='<UUID>')" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "should_be_operated_by__release": <OS RELEASE ID>
}'
```

### Rename device

```bash
PATCH "https://api.balena-cloud.com/v7/device(<ID>)" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "device_name": "<NEW NAME>"
}'
```

### Delete device

```bash
DELETE "https://api.balena-cloud.com/v7/device(<ID>)" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" 
```

### Add note to a device

```bash
PATCH "https://api.balena-cloud.com/v7/device(<ID>)" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "note": "<NEW NOTE>"
}'
```

### Move device to another fleet

```bash
PATCH "https://api.balena-cloud.com/v7/device(<ID>)" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "belongs_to__application": "<FLEET ID>"
}'
```

### Deactivate an offline device (CHARGEABLE)

```bash
PATCH "https://api.balena-cloud.com/v7/device(<ID>)" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "is_active": false
}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.balena.io/reference/api/resources/device.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.