Watches a specific variable and waits for a change in the variable's value. When there is a change, this method returns the new value or times out.

If a variable is deleted while being watched, the variableState state is set to DELETED and the method returns the last known variable value.

If you set the deadline for watching to a larger value than internal timeout (60 seconds), the current variable value is returned and the variableState will be VARIABLE_STATE_UNSPECIFIED.

To learn more about creating a watcher, read the Watching a Variable for Changes documentation.

HTTP request


The URL uses gRPC Transcoding syntax.

Path parameters



The name of the variable to watch, in the format:


Authorization requires the following Google IAM permission on the specified resource name:


Request body

The request body contains data with the following structure:

JSON representation
  "newerThan": string

string (Timestamp format)

If specified, checks the current timestamp of the variable and if the current timestamp is newer than newerThan timestamp, the method returns immediately.

If not specified or the variable has an older timestamp, the watcher waits for a the value to change before returning.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

Response body

If successful, the response body contains an instance of Variable.

Authorization Scopes

Requires one of the following OAuth scopes:


For more information, see the Authentication Overview.

Try it!