Render Variables API

Contents

• Render Variables API

  • Creating a variable

  • Updating a variable

  • Search variables

  • Get variable values

  • Delete a variable

  • Graphing with render variables

Render Variables provide versatility when constructing metric queries. Instead of hard-coding full metric names, use variables as placeholders to dynamically build your queries. This is similar, but not the same as the primary dashboard’s built-in template variables.

NOTE: we advise against using render variables in alert queries.

Creating a variable

POST /v1/variables/<var-name>/

Replace <var-name> with the name you want to give the variable. Place your variable values in a JSON file and include it in the POST request. A variable name is required, however the values can be empty.

Example variable values:

{
  "values": [
    "foobar",
    "foo",
    "bar",
    "baz"
  ]
}

Curl example:

Make sure to include the forward slash character at the end of the request.

Updating a variable

PUT /v1/variables/<var-name>/

Overwrites the values for an existing variable

Curl example:

Search variables

GET /v1/variables/?query=

A “contains” query that will return a JSON object with the name and path of variables that contain the search term. To list all variables, leave the query empty.

Path Parameters

Curl example:

If you have no variables or there are no variables that match your query you will be returned with an empty object:

Get variable values

GET /v1/variables/<var-name>/

Returns a JSON object with the values assigned to <var-name>

Curl example:

Delete a variable

DELETE /v1/variables/<var-name>/

Curl example:

Graphing with render variables

This cannot be done with the simple query builder, you must toggle the edit mode to the free-text mode.

Refer to a render variable by including the variable name enclosed in angled brackets in your metric query: <variable-name>

Using dashboard templates within render variables

You can place template variables within render variables by surrounding them with curly brackets: