Report State

Report State is an important feature which lets the Google Home Action proactively report the latest status of the user's device back to Google Home Graph rather than waiting for a QUERY intent.

Report State reports to Google the states of user devices with the specified agentUserId associated with them (sent in the original SYNC request). When Google Assistant wants to take an action that requires understanding the current state of a device, it can simply look up the state information in the Home Graph instead of issuing a QUERY intent to various third-party clouds prior to issuing the EXECUTE intent.

Without Report State, given lights from multiple providers in a living room, the command Ok Google, brighten my living room requires resolving multiple QUERY intents sent to multiple clouds, as opposed to simply looking up the current brightness values based on what has been previously reported. For the best user experience, Assistant needs to have the current state of a device, without requiring a round-trip to the device.

Following the initial SYNC for a device, the platform sends a QUERY intent that gathers the state of the device to populate Home Graph. After that point, Home Graph only stores the state that is sent with Report State.

When calling Report State, make sure to provide complete state data for a given trait. Home Graph updates states on a per-trait basis and overwrites all data for that trait when a Report State call is made. For example, if you are reporting state for the StartStop trait, the payload needs to include values for both isRunning and isPaused.

Get started

To implement Report State, follow these steps:

• Enable the Google HomeGraph API
• Create a Service Account Key
• Call the API

Enable the Google HomeGraph API

1. In the Google Cloud Console, go to the HomeGraph API page.

   Go to the HomeGraph API page
2. Select the project that matches your smart home project ID.
3. Click ENABLE.

Create a Service Account Key

Follow these instructions to generate a service account key from the Google Cloud Console:

1. In the Google Cloud Console, go to the Service accounts page.

   Go to the Service Accounts page.

   You may need to select a project before you're taken to the Service Accounts page.

2. Click addCreate service account.

3. In the Service account name field, enter a name.

4. In the Service account ID field, enter a ID.

5. In the Service account description field, enter a description.

6. Click Create and continue.

7. From the Role dropdown, select Service Accounts > Service Account OpenID Connect Identity Token Creator.

8. Click Continue.

9. Click Done.

10. Select the service account you just created from the list of service accounts and select Manage keys from the more_vert Actions menu.

11. Select Add key > Create new key.

12. For the Key type, select the JSON option.

13. Click Create. A JSON file that contains your key downloads to your computer.

Call the API

Select an option from the tabs below:

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});
    

  // Get Application Default credentials.
  GoogleCredentials credentials =
      GoogleCredentials.getApplicationDefault()
          .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

  // Create Home Graph service client.
  HomeGraphService homegraphService =
      new HomeGraphService.Builder(
              GoogleNetHttpTransport.newTrustedTransport(),
              GsonFactory.getDefaultInstance(),
              new HttpCredentialsAdapter(credentials))
          .setApplicationName("HomeGraphExample/1.0")
          .build();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request).execute();
}
    

Test Report State

In order to get your Cloud-to-cloud integration ready for certification, it is important to test Report State.

To do this, we recommend using the Home Graph Viewer tool, which is a standalone web app that doesn't require downloading or deployment.

The Report State Dashboard is still available, but is deprecated and no longer supported.

Report State Dashboard

Prerequisites

Before being able to test your Cloud-to-cloud integration, you need your Service Account Key and your agentUserId. If you already have your Service Account Key and agentUserId see Deploy the Report State Dashboard.

Deploy the Report State dashboard

Once you have the Service Account Key and Agent User ID for your project, download and deploy the latest version from Report State Dashboard. Once you have downloaded the latest version, follow the instructions from the included README.MD file.

After you have deployed the Report State dashboard, access the dashboard from the following URL (replace your_project_id with your project ID):

http://<your-project-id>.appspot.com

On the dashboard, do the following:

• Choose your Account Key File
• Add your agentUserId

Then, click List.

All of your devices are listed. Once the list is populated, you can use the Refresh button to update device states. If there is a device state change, the row is highlighted in green.

Report State Discrepancy

The query-based report state accuracy measures how well the latest report state for a device matches the device's status when a user queries for it. This value is expected to be at 99.5%. For more details about the current status of the Report State Accuracy of your project, see Device Health - State accuracy. You can also see the details of Report State Discrepancy Log from the Logs Explorer.

Here is an example of a Report State Discrepancy Log:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Report State Discrepancy Log field definitions

Error Responses

You may receive one of the following error responses when calling Report State. These responses come in the form of HTTP status codes.

400 Bad Request

The server was unable to process the request sent by the client due to invalid syntax. Common causes include malformed JSON or using null instead of "" for a string value.

404 Not Found

The requested resource could not be found but may be available in the future. Typically, this means that we cannot find the requested device. It may also mean that the user account is not linked with Google or we received an invalid agentUserId. Ensure that the agentUserId matches the value provided in your SYNC response, and you are properly handling DISCONNECT intents.

hen a ReportState call fails with a 404 NOT_FOUND error, it indicates a synchronization mismatch between your cloud and Home Graph. This can happen if a device is removed from Home Graph, or if a user unlinks their account.

To handle 404 errors from Report State, use the following procedure:

1. Check user account status: Call devices.sync for the agentUserId that returned a 404 error. This helps determine if the error is for the entire user account or a specific device.
   • If SYNC returns a 404 error, the user account is no longer linked with Google. Stop sending Report State and Request Sync for this user's devices.
   • If SYNC returns 200 OK, the user account is still linked, meaning the 404 error is device-specific.
2. Reconcile device list: If SYNC returns 200 OK, you need to identify which device(s) are no longer known to Google. We recommend you compare the list of devices Google has for the user against your device database, and identify devices in your system that are absent from Google's list. If a device should be synced to Google but it's not yet shared with Google, use SYNC to make sure the device is synced with Google. If a device should be unlinked from Google, stop reporting state for that specific device and continue reporting for other valid devices under that agentUserId.

Online and offline state reporting

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }