Watching a Variable for Changes

This page explains how to create a watcher for a variable. To learn more about watchers, see Runtime Configurator Fundamentals.

Before you begin

Watching a variable for change

You can watch a variable for changes by calling the variables().watch method. The method watches the variable for 60 seconds and returns if the variable value changes. If the value doesn't change within 60 seconds, the method terminates and returns with variable state=VARIABLE_STATE_UNSPECIFIED. If the variable is deleted, the method returns with a variable state=DELETED and the last known variable value.

To set a watcher, use Deployment Manager, the Google Cloud CLI, or the API.

Deployment Manager

This is not supported in Deployment Manager. Create a waiter instead.


With the Google Cloud CLI:

gcloud beta runtime-config configs variables watch [VARIABLE_KEY] --max-wait [TIMEOUT_SEC] --config-name [CONFIG_NAME]


  • [VARIABLE_KEY] is the key to watch.
  • [TIMEOUT_SEC] is the time in seconds to wait. The default and maximum amount is 60 seconds.

The gcloud CLI watches the variable and returns after it reaches the specified timeout period or the variable changes. If the variable changed, the response contains one of the applicable variable states.


In the API, make a POST request to the following URI:[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]:watch


  • [PROJECT_ID] is the project ID for this request.
  • [CONFIG_NAME] is the name of the RuntimeConfig resource for this request.
  • [VARIABLE_KEY] is the key to watch.

    Optionally, you can provide a request payload with the newerThan property:

    { "newerThan": "[TIMESTAMP]" }

    where [TIMESTAMP] is a timestamp in RFC 3339 since the epoch in UTC "Zulu" format. For example:


    If you provide the newerThan property, the method returns immediately if the current timestamp for the variable is newer than the specified timestamp. Use the newerThan property to make sure you didn't miss any changes between watch() calls.

    The method returns with one of applicable variable states.

    To learn more about the method, read the variables().watch documentation.

What's next