# 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](https://docs.luxonis.com/cloud/api/graphql.md).

You'll also need an API key to authenticate your requests. Use [API Keys](https://docs.luxonis.com/cloud/api/api-keys.md) to
create one in the Luxonis Hub web UI, then include it in the Authorization header:

```bash
Authorization: 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
query {
  team {
    devices(first: 10) {
      nodes {
        id
        name
        status
        model
        architecture
        version
        lastContactAt
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

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

### Paginate through a larger fleet

To fetch the next page, pass the previous endCursor into after.

```graphql
query($after: String) {
  team {
    devices(first: 10, after: $after) {
      nodes {
        id
        name
        status
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

Variables:

```json
{
  "after": "cursor_from_previous_response"
}
```

### Filter devices by status or group

Filter devices by status or by device group when the workflow needs a narrower device set.

```graphql
query {
  team {
    devices(filter: { status: ONLINE }, first: 10) {
      nodes {
        id
        name
        status
      }
    }
  }
}
```

Available filters include:

 * status: ONLINE or OFFLINE
 * deviceGroupId: filter by specific device group ID
 * adoptKeyId: filter devices adopted by a specific adopt key

## Inspect one device

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

```graphql
query($deviceId: ID!) {
  team {
    device(deviceId: $deviceId) {
      id
      name
      status
      model
      serialNumber
      architecture
      kind
      capabilities
      version
      lastContactAt
      lastStatusChangeAt
      networkInterfaces {
        interfaceName
        ipv4Address
        macAddress
      }
      availableUpgrade {
        id
        version
        semver
      }
    }
  }
}
```

Variables:

```json
{
  "deviceId": "device-id-from-list"
}
```

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](https://docs.luxonis.com/cloud/api/guides/integration-architecture.md).

## 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.

[Mutations reference](https://docs.luxonis.com/cloud/api/reference/control-api/mutations.md)

### Manage applications

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

[Manage applications](https://docs.luxonis.com/cloud/features/application-management/manage-applications.md)

### Update device (OTA)

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

[Update device (OTA)](https://docs.luxonis.com/cloud/features/device-management/ota-updates.md)

### Streaming and visualizer

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

[Streaming and visualizer](https://docs.luxonis.com/cloud/api/guides/streaming-and-visualizer.md)