# action.devices.QUERY

This intent queries your fulfillment for the current states of devices, including whether the device is online and reachable.

Your `QUERY` response should return only state information.
Updating the attributes and traits of the device is handled by the
[`SYNC`](https://developers.home.google.com/cloud-to-cloud/intents/sync) response.

For more details, see [Query and execute](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).


## Request format

| Fields | Type | Description |
|---|---|---|
| `requestId` | *String* | **Required.** ID of the request. |
| `inputs` | *Array* | **Required.** List of inputs matching the intent request. |
| `[*item, ...*]` | *Object* | Type and payload associated with the intent request. |
| `intent` |   | **Required.** (Constant value: `"action.devices.QUERY"`) Intent request type. |
| `payload` | *Object* | **Required.** QUERY request payload. |
| `devices` | *Array* | **Required.** List of target devices. |
| `[*item, ...*]` | *Object* | Device targets to query. |
| `id` | *String* | **Required.** Device ID, as per the ID provided in SYNC. |
| `customData` | *Object* | If the opaque customData object is provided in SYNC, it's sent here. |

##### Examples

*QUERY intent request*

```
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123",
            "customData": {
              "fooValue": 74,
              "barValue": true,
              "bazValue": "foo"
            }
          },
          {
            "id": "456",
            "customData": {
              "fooValue": 12,
              "barValue": false,
              "bazValue": "bar"
            }
          }
        ]
      }
    }
  ]
}
```

## Response format

| Fields | Type | Description |
|---|---|---|
| `requestId` | *String* | **Required.** ID of the corresponding request. |
| `payload` | *Object* | **Required.** Intent response payload. |
| `errorCode` | *String* | An error code for the entire transaction for auth failures and developer system unavailability. For individual device errors use the errorCode within the device object. |
| `debugString` | *String* | Detailed error which will never be presented to users but may be logged or used during development. |
| `devices` | *Object* | **Required.** Map of devices. Maps developer device ID to object of state properties. |
| `<string>` | *Object* | Device state. |
| `online` | *Boolean* | **Required.** Indicates if the device is online (that is, reachable) or not. |
| `status` | *String* | **Required.** Result of the query operation. Supported values: `SUCCESS` :   Confirm that the query succeeded. `OFFLINE` :   Target device is in offline state or unreachable. `EXCEPTIONS` :   There is an issue or alert associated with a query. The query could succeed or fail. This status type is typically set when you want to send additional information about another connected device. `ERROR` :   Unable to query the target device. |
| `errorCode` | *String* | Expanding ERROR state if needed from the preset error codes, which will map to the errors presented to users. |

##### Examples

*QUERY intent response*

```
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true,
        "status": "SUCCESS"
      },
      "456": {
        "on": true,
        "online": true,
        "status": "SUCCESS",
        "brightness": 80,
        "color": {
          "spectrumRgb": 16711935
        }
      }
    }
  }
}
```