Update an exploration

Updates an existing exploration by its ID. You only need to provide the fields you want to change.

When updating nested resources like queries or variables, the entire array will be replaced with the one you provide.

PATCH https://telemetry.betterstack.com/api/v2/explorations/{id}

URL parameters

required integer

The unique identifier of the exploration to update.

Headers

Authorization

required string

Bearer $TOKEN

Body parameters

name

string

A new name for the exploration.

date_range_from

string

A new start for the exploration's date range.

date_range_to

string

A new end for the exploration's date range.

exploration_group_id

integer

A new exploration group ID. Use 0 or null to remove from a group.

chart

object

An object to update the chart's configuration. The entire object is replaced.

queries

array

An array of query objects to replace the existing queries.

variables

array

An array of variable objects to replace the existing custom variables.

200

The exploration was updated successfully.

Response body

{
  "data": {
    "id": 123,
    "type": "exploration",
    "attributes": {
      "name": "Updated Error Rate Analysis",
      "date_range_from": "now-3h",
      "date_range_to": "now",
      "exploration_group_id": 456,
      "created_at": "2026-02-20T10:00:00Z",
      "updated_at": "2026-02-24T11:00:00Z",
      "chart": {
        "chart_type": "line_chart",
        "name": "Updated Error Rate Analysis",
        "description": "Shows error rates across all services",
        "settings": {
          "unit": "number"
        }
      },
      "queries": [
        {
          "id": 2,
          "name": "Updated Query",
          "query_type": "sql_expression",
          "sql_query": "SELECT {{time}} AS time, sum(errors) AS value FROM {{source}} WHERE time BETWEEN {{start_time}} AND {{end_time}} GROUP BY time",
          "source_variable": "source"
        }
      ],
      "variables": [
        {
          "name": "source",
          "variable_type": "source",
          "default_values": [
            "123"
          ]
        }
      ]
    }
  }
}

404

An exploration with the specified ID was not found.

Example Request

This example updates the exploration's name and replaces its queries.

cURL

Copied!

curl --request PATCH \
  --url https://telemetry.betterstack.com/api/v2/explorations/123 \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Updated Error Rate Analysis",
    "queries": [
      {
        "name": "Updated Query",
        "query_type": "sql_expression",
        "sql_query": "SELECT {{time}} AS time, sum(errors) AS value FROM {{source}} WHERE time BETWEEN {{start_time}} AND {{end_time}} GROUP BY time",
        "source_variable": "source"
      }
    ]
  }'

Create an exploration

Remove an exploration

Explore documentation

Update an exploration

Example Request

Please accept cookies