# Method: projects.locations.clusters.watchEvents

- [HTTP request](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#body.WatchEventsResponse.SCHEMA_REPRESENTATION)
- [Authorization Scopes](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#body.aspect)
- [IAM Permissions](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#body.aspect_1)
- [EventUpdateFilter](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#EventUpdateFilter)
  - [JSON representation](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#EventUpdateFilter.SCHEMA_REPRESENTATION)
- [SpecialMode](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#SpecialMode)
- [EventUpdateType](https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#EventUpdateType)

Watch for event updates happening on the given streams.

### HTTP request

`POST https://{endpoint}/v1/{cluster=projects/*/locations/*/clusters/*}:watchEvents`

Where `{endpoint}` is one of the [supported service endpoints](https://docs.cloud.google.com/vision-ai/docs/reference/rest#rest_endpoints).

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

### Path parameters

| Parameters ||
|---|---|
| `cluster` | `string` The parent of the resource. |

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "watcherId": string, "streams": [ string ], "eventUpdateFilter": { object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#EventUpdateFilter`) }, "heartbeatIntervalSecond": number } ``` |

| Fields ||
|---|---|
| `watcherId` | `string` Unique ID identifies the watcher of the streams. |
| `streams[]` | `string` The name of the stream or the set of streams to watch. |
| `eventUpdateFilter` | ``object (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#EventUpdateFilter`)`` The filter that the watchers can speficy on which event updates that they want to receive. |
| `heartbeatIntervalSecond` | `number` HeartbeatIntervalSecond defines the interval (in second) of heartbeat response returned from the gRPC streaming server. Default 0 means no heartbeat will be returned. |

### Response body

If successful, the response body contains data with the following structure:
Each response message will contain one Event update.

| JSON representation |
|---|
| ``` { "updateType": enum (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#EventUpdateType`), "stream": string, "event": string, "series": string, "updateTime": string } ``` |

| Fields ||
|---|---|
| `updateType` | ``enum (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#EventUpdateType`)`` The type of the Event update. |
| `stream` | `string` The name of the stream that the event is attached to. |
| `event` | `string` The name of the event. |
| `series` | `string` The name of the series. |
| `updateTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` The timestamp when the Event update happens. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |

### Authorization Scopes

Requires the following OAuth scope:

- `https://www.googleapis.com/auth/cloud-platform`

For more information, see the [Authentication Overview](https://cloud.google.com/docs/authentication/).

### IAM Permissions

Requires the following [IAM](https://cloud.google.com/iam/docs) permission on the `cluster` resource:

- `visionai.clusters.watch`

For more information, see the [IAM documentation](https://cloud.google.com/iam/docs).

## EventUpdateFilter

EventUpdateFilter is the filter that the watchers can speficy on which event updates that they want to receive.

| JSON representation |
|---|
| ``` { // Union field `start_time` can be only one of the following: "specialMode": enum (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#SpecialMode`), "specificTime": string // End of list of possible types for union field `start_time`. } ``` |

| Fields ||
|---|---|
| Union field `start_time`. `start_time` can be only one of the following: ||
| `specialMode` | ``enum (`https://docs.cloud.google.com/vision-ai/docs/reference/rest/v1/projects.locations.clusters/watchEvents#SpecialMode`)`` Special modes other than a specific timestamp. |
| `specificTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` Specific timestamp after which the event updates happens. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |

## SpecialMode

Special modes other than a specific timestamp.

| Enums ||
|---|---|
| `SPECIAL_MODE_UNSPECIFIED` | Special mode unspecified. |
| `BEGINNING` | BEGINNING special mode means all currently available events and incoming event updates. |
| `LATEST` | LATEST special mode means only the latest events and incoming event updates. |

## EventUpdateType

The type of the event updates. Can be extended in the future for other use cases. e.g. EVENT_DETACHED_FROM_STREAM, and more.

| Enums ||
|---|---|
| `EVENT_UPDATE_TYPE_UNSPECIFIED` | Event update type unspecified. |
| `EVENT_AVAILABLE_ON_STREAM` | Event is available to read from on a stream. |
| `EVENT_HEARTBEAT` | Heartbeat message that is used to track liveliness of the gRPC connection. |