List devices and inspect device state

Use this guide when you need to enumerate devices in your Luxonis Hub team, inspect one device in detail, and decide whether to continue into app lifecycle or supported update actions.

Prerequisites

Before starting, you should be familiar with GraphQL basics. If you're new to GraphQL, check out About GraphQL.You'll also need an API key to authenticate your requests. Use API Keys to create one in the Luxonis Hub web UI, then include it in the Authorization header:

Command Line

1Authorization: Bearer <your_api_key>

Keep API keys on your backend

API keys can access your team's public control-plane surface. Store them in your backend or other server-side tooling, not in an untrusted client.

List devices

Start by querying the devices visible to your team. This gives you the device IDs you will use for follow-up reads or mutations.

Graphql

1query {
2  team {
3    devices(first: 10) {
4      nodes {
5        id
6        name
7        status
8        model
9        architecture
10        version
11        lastContactAt
12      }
13      pageInfo {
14        hasNextPage
15        endCursor
16      }
17    }
18  }
19}

Use this response to answer the first practical questions quickly:

which devices exist in the team
whether they are currently ONLINE or OFFLINE
which device ID to carry into the next query
whether more pages exist

Inspect one device

Use one device ID from the list query to retrieve the operational details you need before taking action.

Graphql

1query($deviceId: ID!) {
2  team {
3    device(deviceId: $deviceId) {
4      id
5      name
6      status
7      model
8      serialNumber
9      architecture
10      kind
11      capabilities
12      version
13      lastContactAt
14      lastStatusChangeAt
15      networkInterfaces {
16        interfaceName
17        ipv4Address
18        macAddress
19      }
20      availableUpgrade {
21        id
22        version
23        semver
24      }
25    }
26  }
27}

Variables:

JSON

1{
2  "deviceId": "device-id-from-list"
3}

Use this response to confirm:

the device identity and current connection state
whether the target is OAK or SELF_HOSTED
which capabilities are available for the device path
whether network details explain the current reachability state
whether availableUpgrade exposes a supported update candidate

Request only the fields your workflow needs

The GraphQL selection set is flexible. Start with the fields above, then trim or expand the query based on what your device-management workflow actually uses.

Move from inspection to action

After you can list devices and inspect one target, the next step is usually to act on that state rather than jump straight into an interactive browser session.The common next jobs are:

install an app on the device or inspect installed app state
start or stop an installed app
trigger a supported OTA or firmware update when availableUpgrade is present
use browser-side sessions only when the goal is remote interaction, logs, or visualization rather than a control-plane action

For external integrations, keep write operations on your backend and follow the customer-owned architecture described in Integration Architecture.

Verify the result

You are ready for the next workflow when all of the following are true:

you can call team.devices and receive the expected fleet slice
you can take one returned device ID and call team.device
you can tell whether the device is online, what version it is running, and whether supported update data is present
you know whether the next step is an app lifecycle mutation, an update flow, or an interactive session

Next steps

Mutations reference

Continue from device reads into team-scoped write operations such as device and app management mutations.

Manage applications

Install applications, control run state, and understand the next operational steps after device inspection.

Update device (OTA)

See which update paths are supported today and how OTA actions relate to device state.

Streaming and visualizer

Use this path when the next job is browser-side live interaction rather than a control-plane action.

ON THIS PAGE