# Method: devices.query

- [HTTP request](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#body.HTTP_TEMPLATE)
- [Request body](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#body.request_body)
  - [JSON representation](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#body.response_body)
  - [JSON representation](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#body.QueryResponse.SCHEMA_REPRESENTATION)
- [Authorization Scopes](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#body.aspect)
- [QueryRequestInput](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryRequestInput)
  - [JSON representation](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryRequestInput.SCHEMA_REPRESENTATION)
- [QueryRequestPayload](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryRequestPayload)
  - [JSON representation](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryRequestPayload.SCHEMA_REPRESENTATION)
- [AgentDeviceId](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#AgentDeviceId)
  - [JSON representation](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#AgentDeviceId.SCHEMA_REPRESENTATION)
- [QueryResponsePayload](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryResponsePayload)
  - [JSON representation](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryResponsePayload.SCHEMA_REPRESENTATION)

Gets the current states in Home Graph for the given set of the third-party user's devices.

The third-party user's identity is passed in via the `agentUserId` (see `QueryRequest`). This request must be authorized using service account credentials from your Actions console project.

### HTTP request

`POST https://homegraph.googleapis.com/v1/devices:query`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "requestId": string, "agentUserId": string, "inputs": [ { object (`https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryRequestInput`) } ] } ``` |

| Fields ||
|---|---|
| `requestId` | `string` Request ID used for debugging. |
| `agentUserId` | `string` Required. Third-party user ID. |
| `inputs[]` | ``object (`https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryRequestInput`)`` Required. Inputs containing third-party device IDs for which to get the device states. |

### Response body

If successful, the response body contains data with the following structure:
Response type for the [`devices.query`](https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#google.home.graph.v1.HomeGraphApiService.Query) call. This should follow the same format as the Google smart home `action.devices.QUERY` [response](https://developers.home.google.com/cloud-to-cloud/intents/query).

Example:

    {
      "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
      "payload": {
        "devices": {
          "123": {
            "on": true,
            "online": true
          },
          "456": {
            "on": true,
            "online": true,
            "brightness": 80,
            "color": {
              "name": "cerulean",
              "spectrumRGB": 31655
            }
          }
        }
      }
    }

| JSON representation |
|---|
| ``` { "requestId": string, "payload": { object (`https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryResponsePayload`) } } ``` |

| Fields ||
|---|---|
| `requestId` | `string` Request ID used for debugging. Copied from the request. |
| `payload` | ``object (`https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryResponsePayload`)`` Device states for the devices given in the request. |

### Authorization Scopes

Requires the following OAuth scope:

- `https://www.googleapis.com/auth/homegraph`

For more information, see the [OAuth 2.0 Overview](https://developers.google.com/identity/protocols/OAuth2).

## QueryRequestInput

Device ID inputs to `QueryRequest`.

| JSON representation |
|---|
| ``` { "payload": { object (`https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryRequestPayload`) } } ``` |

| Fields ||
|---|---|
| `payload` | ``object (`https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#QueryRequestPayload`)`` Payload containing third-party device IDs. |

## QueryRequestPayload

Payload containing device IDs.

| JSON representation |
|---|
| ``` { "devices": [ { object (`https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#AgentDeviceId`) } ] } ``` |

| Fields ||
|---|---|
| `devices[]` | ``object (`https://developers.home.google.com/reference/home-graph/rest/v1/devices/query#AgentDeviceId`)`` Third-party device IDs for which to get the device states. |

## AgentDeviceId

Third-party device ID for one device.

| JSON representation |
|---|
| ``` { "id": string } ``` |

| Fields ||
|---|---|
| `id` | `string` Third-party device ID. |

## QueryResponsePayload

Payload containing device states information.

| JSON representation |
|---|
| ``` { "devices": { string: { object }, ... } } ``` |

| Fields ||
|---|---|
| `devices` | ``map (key: string, value: object (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Struct` format))`` States of the devices. Map of third-party device ID to struct of device states. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |