Listing Devices

Contents#

• Listing Devices
  • By User
    • Narrowing your selection
      • Limit number of results
      • Next page of results
      • Specify trait names
      • Per linked account ID
  • By LinkedAccount
  • By Device ID

The platform provides multiple points of access for getting information about connected devices. This guide serves as a list of examples and explanations for these interfaces.

By User#

Listing devices by user starts with a query targeting the current user: me. Below is a query that will return a paginated list of device IDs. For more information on pagination see limiting number of results and getting the next page of results.

me {
  devices {
    edges {
      node {
        id
      }
    }
  }
}

Narrowing your selection#

To more efficiently access a large number of devices, we recommend using the following features to limit/narrow the results of a device query.

Limit number of results#

By default, the devices query will return 10 results. You can change the number of device results returned by using the first parameter. To maximize efficiency and ensure low latency, try to keep this number low and use pagination where possible.

devices (
  first: 10
) {
  pageInfo { hasNextPage }
}

Next page of results#

Users may have more connected devices than can be returned by the platform in a single query. To access these devices, we provide pagination mechanisms. Under the devices response object we provide a pageInfo object which contains properties like hasNextPage and endCursor. They can be used repeatedly until hasNextPage returns false.

devices (
  after: "<endCursor>"
) {
  pageInfo {
    hasNextPage
    endCursor
  }
}

Specify trait names#

When attempting to work with a subset of devices that provide a unified feature set, we can filter the returned devices by the Traits they expose.

devices (
  filter: { traits: [POWER, BRIGHTNESS] }
) {
  ...
}

Per linked account ID#

To retrieve all devices belonging to a specific third-party account, provide the linkedAccountId in the query’s parameters.

devices (
  linkedAccountId: "<ID>"
) {
  ...
}

By LinkedAccount#

To list devices organized by LinkedAccount, drill into the linkedAccounts connection from the me object, then paginate the device results. For example:

me {
  linkedAccounts {
    edges {
      node {
        devices {
          ...
        }
      }
    }
  }
}

By Device ID#

To access a specific device by ID, use the device query.

device(id: "<ID>") {
  id
}