Create an exploration

Creates a new exploration, including its chart, queries, and variables.

The Explorations API is only available for the Telemetry product. Requests must be sent to telemetry.betterstack.com, and only explorations with product: "telemetry" can be managed.

POST https://telemetry.betterstack.com/api/v2/explorations

Headers

Authorization

required string

Bearer $TOKEN

Body parameters

name

required string

The name of the exploration. This is also set as the chart's name.

chart

required object

An object defining the chart's type and settings. chart_type is required.

queries

required array

An array of one or more query objects. At least one query is required.

date_range_from

now-3h string

The start of the exploration's date range.

date_range_to

now string

The end of the exploration's date range.

exploration_group_id

integer

The ID of an exploration group to organize this exploration. Use 0 to remove it from a group.

variables

array

An array of custom query variable objects. Default variables (time, start_time, end_time, source) are created automatically.

team_name

string

Required if using a global API token to specify which team should own the resource.

201

The exploration was created successfully.

Response body

{
  "data": {
    "id": 123,
    "type": "exploration",
    "attributes": {
      "name": "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-20T10:00:00Z",
      "chart": {
        "chart_type": "line_chart",
        "description": "Shows error rates across all services",
        "settings": {
          "unit": "number",
          "decimal_places": 0,
          "legend": "bottom",
          "stacking": "dont_stack"
        }
      },
      "queries": [
        {
          "id": 1,
          "name": "Main Query",
          "query_type": "sql_expression",
          "sql_query": "SELECT {{time}} AS time, count(*) 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"
          ]
        },
        {
          "name": "log_level",
          "variable_type": "select_value",
          "values": [
            "error",
            "warning",
            "info"
          ],
          "default_values": [
            "error"
          ]
        }
      ]
    }
  }
}

422

Validation failed due to invalid parameters.

Response body

{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "name": [
      "can't be blank"
    ]
  }
}

Example Request

cURL

Copied!

curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/explorations \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Error Rate Analysis",
    "date_range_from": "now-3h",
    "date_range_to": "now",
    "exploration_group_id": 456,
    "chart": {
      "chart_type": "line_chart",
      "description": "Shows error rates across all services",
      "settings": {
        "unit": "number",
        "decimal_places": 0,
        "legend": "bottom",
        "stacking": "dont_stack"
      }
    },
    "queries": [
      {
        "name": "Main Query",
        "query_type": "sql_expression",
        "sql_query": "SELECT {{time}} AS time, count(*) 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"]
      },
      {
        "name": "log_level",
        "variable_type": "select_value",
        "values": ["error", "warning", "info"],
        "default_values": ["error"]
      }
    ]
  }'

Reference

The following tables provide details on supported chart types, query types, settings, and variables.

Chart Types

Value	Description	Multiple Queries
`line_chart`	Time series line chart	Yes
`bar_chart`	Bar chart	No
`pie_chart`	Pie/donut chart	No
`scatter_chart`	Scatter plot	No
`gauge_chart`	Gauge/meter visualization	No
`number_chart`	Single number display	No
`heatmap_chart`	Heatmap visualization	No
`table_chart`	Tabular data display	No
`map_chart`	Geographic visualization	No
`text_chart`	Dynamic text with query data	No
`tail_chart`	Live tail log stream	No
`static_text_chart`	Static markdown text	No

Query Types

Value	Description	API Support
`sql_expression`	SQL query	Full (create, read, update)
`tail_query`	Live Tail / Log filtering query	Full (create, read, update)
`static_text`	Static markdown text	Full (create, read, update)
`pql_expression`	PQL query	Read-only
`query_builder`	Drag & drop visual query builder	Read-only
`funnel_query`	Funnel analysis query	Read-only

Read-only query types (pql_expression, query_builder) cannot be created or modified via the API as they require client-side compilation to SQL.

Chart-Query Compatibility

Chart Type	Allowed Query Types
`line_chart`	`sql_expression`, `pql_expression`, `tail_query`, `query_builder`
`bar_chart`	`sql_expression`, `pql_expression`, `tail_query`, `query_builder`
`pie_chart`	`sql_expression`, `pql_expression`, `query_builder`
`scatter_chart`	`sql_expression`, `pql_expression`, `query_builder`
`gauge_chart`	`sql_expression`, `pql_expression`, `tail_query`, `query_builder`
`number_chart`	`sql_expression`, `pql_expression`, `tail_query`, `query_builder`
`heatmap_chart`	`sql_expression`, `pql_expression`, `query_builder`
`table_chart`	`sql_expression`, `pql_expression`, `query_builder`
`map_chart`	`sql_expression`, `pql_expression`, `query_builder`
`text_chart`	`sql_expression`, `pql_expression`, `tail_query`, `query_builder`
`tail_chart`	`tail_query` (required)
`static_text_chart`	`static_text` (required)

Variable Types

Value	Description
`source`	Data source reference (`default_values` are source IDs)
`string`	String value (quoted in queries)
`number`	Numeric value
`date`	Date value
`datetime`	DateTime with microseconds
`boolean`	TRUE/FALSE/NULL
`sql_expression`	Raw SQL expression (no escaping)
`select_value`	Predefined string values (requires `values` array)
`select_with_sql`	Values from SQL query (requires `sql_definition`)

Get a single exploration

Update an exploration

Explore documentation

Create an exploration

Example Request

Reference

Chart Types

Query Types

Chart-Query Compatibility

Variable Types

Please accept cookies