---
title: "POST /v1/devices:reportStateAndNotification"
method: POST
path: "/v1/devices:reportStateAndNotification"
tags: ["devices"]
---

# POST /v1/devices:reportStateAndNotification

`POST /v1/devices:reportStateAndNotification`

Reports device state and optionally sends device notifications. Called by your smart home Action when the state of a third-party device changes or you need to send a notification about the device. See [Implement Report State](https://developers.home.google.com/cloud-to-cloud/integration/report-state) for more information. This method updates the device state according to its declared [traits](https://developers.home.google.com/cloud-to-cloud/primer/device-types-and-traits). Publishing a new state value outside of these traits will result in an `INVALID_ARGUMENT` error response. The third-party user's identity is passed in via the `agent_user_id` (see ReportStateAndNotificationRequest). This request must be authorized using service account credentials from your Actions console project.

## Request body

- ReportStateAndNotificationRequest — Request type for the [`ReportStateAndNotification`](#google.home.graph.v1.HomeGraphApiService.ReportStateAndNotification) call. It may include states, notifications, home_traits, home_events, or any combination thereof. Smart Home Device Traits (SHDT) `states` and `notifications` are defined per `device_id` (for example, "123" and "456" in the following example). Google Home Traits `home_traits` and `home_events` are lists of updates or events, each associated with a `device_id` (for example, "789" in the following example). Example: ```json { "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "1234", "payload": { "devices": { "states": { "123": { "on": true }, "456": { "on": true, "brightness": 10 }, }, "homeTraits": [ { "deviceId": "789", "components": [ { "componentId": "main", "traitData": [ { "trait": { "@type": "type.googleapis.com/home.graph.v1.OnOffTrait", "onOff": true } } ] } ] } ], "homeEvents": [ { "deviceId": "789", "events": [ { "componentId": "main", "events": [ { "eventId": "event-123", "eventTime": "2026-01-01T00:00:00Z", "event": { "@type": "type.googleapis.com/home.graph.v1.DoorbellPressTrait.DoorbellPressedEvent" } } ] } ] } ] } } } ```
  - `eventId` string — Unique identifier per event (for example, a doorbell press).
  - `followUpToken` string — Deprecated.
  - `requestId` string — Request ID used for debugging.
  - `agentUserId` string — Required. Third-party user ID.
  - `payload` StateAndNotificationPayload — Payload containing the state and notification information for devices.
    - `devices` ReportStateAndNotificationDevice — The states and notifications specific to a device.
      - `homeTraits` HomeTraitUpdates[] — Optional. UDDM/WHDM trait updates.
        - `deviceId` string — Required. Unique identifier for the device.
        - `components` ComponentTraitUpdates[] — Required. Trait updates for each component.
          - `traitData` TraitData[] — Required. The updated trait data for the component.
            - `commitTime` string, google-datetime — Other metadata for the trait. The time the client update was committed in the server.
            - `trait` object — The Provider Home API trait payload.
          - `componentId` string — Required. ID of the component from the device provider.
      - `states` object — States of devices to update. See the **Device STATES** section of the individual trait [reference guides](https://developers.home.google.com/cloud-to-cloud/traits).
      - `homeEvents` HomeEvents[] — Optional. UDDM/WHDM trait events
        - `events` Events[] — Required. List of events for the item.
          - `componentId` string — Optional. The ID of the provider component if the events are associated with a specific component. Optional for WHDM events, required for UDDM events.
          - `events` EventData[] — Required. List of events associated with the component.
            - `eventId` string — Required. The unique event ID from the device provider.
            - `event` object — Required. The actual event payload.
            - `eventTime` string, google-datetime — Required. The timestamp of the event.
        - `deviceId` string — Required. / Unique identifier for the device.
      - `notifications` object — Notifications metadata for devices. See the **Device NOTIFICATIONS** section of the individual trait [reference guides](https://developers.home.google.com/cloud-to-cloud/traits).

## Response `200`

Successful response

---

[API](https://skmtc.net/google/apis/homegraph.md) · [All operations](https://skmtc.net/google/apis/homegraph/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/homegraph/versions/28c601cbc091/schema)