# Update an exploration

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

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

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/explorations/{id}"
method = "PATCH"

[[path_param]]
name = "id"
description = "The unique identifier of the exploration to update."
required = true
type = "integer"

[[body_param]]
name = "name"
description = "A new name for the exploration."
required = false
type = "string"

[[body_param]]
name = "date_range_from"
description = "A new start for the exploration's date range."
required = false
type = "string"

[[body_param]]
name = "date_range_to"
description = "A new end for the exploration's date range."
required = false
type = "string"

[[body_param]]
name = "exploration_group_id"
description = "A new exploration group ID. Use `0` or `null` to remove from a group."
required = false
type = "integer"

[[body_param]]
name = "chart"
description = "An object to update the chart's configuration. The entire object is replaced."
required = false
type = "object"

[[body_param]]
name = "queries"
description = "An array of query objects to replace the existing queries."
required = false
type = "array"

[[body_param]]
name = "variables"
description = "An array of variable objects to replace the existing custom variables."
required = false
type = "array"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = "The exploration was updated successfully."
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"] }
      ]
    }
  }
}
'''

[[response]]
status = 404
description = "An exploration with the specified ID was not found."
[/responses]

## Example request

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

```shell
[label cURL]
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"
      }
    ]
  }'
```