Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. metrics
  4. Ingesting data
    1. Better Stack collector
    2. OpenTelemetry
    3. Vector
    4. Ingesting via HTTP API
    5. Ingesting metrics
    6. Ingesting logs
    7. Migrating to Better Stack
  5. Using the product
    1. AI SRE ↗
    2. MCP server ↗
    3. Transforming ingested data
    4. Querying data
    5. Tracing
    6. Grafana
    7. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources & collectors
    3. Dashboards
    4. Explorations
      1. Explorations API
        1. List all explorations GET
        2. Get a single exploration GET
        3. Create an exploration POST
        4. Update an exploration PATCH
        5. Remove an exploration DELETE
      2. Exploration alerts API
      3. Exploration groups API
    5. Alerts API
    6. Connections API
    7. Query API ↗
    8. Usage API ↗
  7. Alternative to
    1. Lightstep

Get a single exploration

Retrieves a single exploration by its ID, including the full chart, query, and variable configurations.

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

URL parameters

id
required integer

The unique identifier of the exploration.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns the exploration.

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:00.000Z",
      "updated_at": "2026-02-23T14:30:00.000Z",
      "chart": {
        "chart_type": "line_chart",
        "name": "Error Rate Analysis",
        "description": "Shows error rates across all services",
        "settings": {
          "unit": "number",
          "decimal_places": 2,
          "legend": "bottom",
          "stacking": "dont_stack",
          "x_axis_type": "time"
        }
      },
      "queries": [
        {
          "id": 1,
          "name": "Main Query",
          "query_type": "sql_expression",
          "source_variable": "source",
          "sql_query": "SELECT {{time}} AS time, count(*) AS value FROM {{source}} WHERE time BETWEEN {{start_time}} AND {{end_time}} GROUP BY time"
        }
      ],
      "variables": [
        {
          "name": "time",
          "variable_type": "datetime",
          "values": [],
          "default_values": [],
          "allow_multiple_values": false
        },
        {
          "name": "start_time",
          "variable_type": "datetime",
          "values": [],
          "default_values": [],
          "allow_multiple_values": false
        },
        {
          "name": "end_time",
          "variable_type": "datetime",
          "values": [],
          "default_values": [],
          "allow_multiple_values": false
        },
        {
          "name": "source",
          "variable_type": "source",
          "values": [
            "123"
          ],
          "default_values": [
            "123"
          ],
          "structured_value": {
            "canonicalSourceIds": [
              "t123456_my_app:logs"
            ]
          },
          "allow_multiple_values": false
        },
        {
          "name": "log_level",
          "variable_type": "select_value",
          "values": [
            "error",
            "warning",
            "info"
          ],
          "default_values": [
            "error"
          ],
          "allow_multiple_values": false
        }
      ]
    }
  }
}
401

Invalid or missing authentication token.

404

An exploration with the specified ID was not found.

Response body

{
  "errors": "Resource with the provided ID was not found"
}

Response attributes

id
string

The ID of the exploration.

type
string

Always exploration.

attributes.name
string

The name of the exploration, generated from its query when it still has the default name.

attributes.date_range_from
string

The start of the exploration's time range, for example now-3h.

attributes.date_range_to
string

The end of the exploration's time range, for example now.

attributes.exploration_group_id
integer or null

The ID of the exploration group, or null when the exploration isn't in a group.

attributes.created_at
string

When the exploration was created, as an ISO 8601 date-time in UTC.

attributes.updated_at
string

When the exploration was last updated, as an ISO 8601 date-time in UTC.

attributes.chart
object

The chart that shows the exploration.

attributes.chart.chart_type
string

The chart type: line_chart, bar_chart, pie_chart, scatter_chart, gauge_chart, number_chart, heatmap_chart, table_chart, map_chart, text_chart, tail_chart, static_text_chart, funnel_chart, funnel_trend_chart, anomalies_chart, or hierarchy_chart.

attributes.chart.name
string

The name of the chart as stored, which name replaces with a generated name while it is the default.

attributes.chart.description
string or null

The description of the chart, or null when it has none.

attributes.chart.settings
object

The chart's display settings, such as unit, decimal_places, and legend.

attributes.queries
array

The queries the chart runs.

attributes.queries[].id
integer

The ID of the query.

attributes.queries[].name
string

The name of the query. Omitted when not set.

attributes.queries[].query_type
string

The type of the query: sql_expression, tail_query, tail_query_builder, promql_query, promql_v2_query, promql_via_llm, query_builder, static_text, pql_expression, or funnel_query.

attributes.queries[].source_variable
string

The sources the query reads, either the name of a source variable such as source or a source: reference to specific sources. Omitted when not set.

attributes.queries[].sql_query
string

The SQL the query runs. Present for sql_expression, pql_expression, query_builder, tail_query_builder, and funnel_query queries, and omitted when not set.

attributes.queries[].pql_query
string

The PQL the query is written in. Present only for pql_expression queries.

attributes.queries[].where_condition
string

The filter of the query. Present only for tail_query and tail_query_builder queries, and omitted when not set.

attributes.queries[].static_text
string

The Markdown content of the query. Present only for static_text queries, and omitted when not set.

attributes.queries[].funnel_query
object

The funnel definition with its session field, steps, and breakdown. Present only for funnel_query queries, and omitted when not set.

attributes.queries[].x_axis
array

The query builder's X axis blocks. Present only for query_builder and tail_query_builder queries, as an empty array when there are none.

attributes.queries[].y_axis
array

The query builder's Y axis blocks. Present only for query_builder and tail_query_builder queries, and omitted when not set.

attributes.queries[].point_size
array

The query builder's point size blocks. Present only for query_builder and tail_query_builder queries, and omitted when not set.

attributes.queries[].coordinates
array

The query builder's coordinate blocks. Present only for query_builder and tail_query_builder queries, as an empty array when there are none.

attributes.queries[].filters
array

The query builder's filter blocks. Present only for query_builder and tail_query_builder queries, and omitted when not set.

attributes.queries[].where
array

The query builder's WHERE condition blocks. Present only for query_builder and tail_query_builder queries, as an empty array when there are none.

attributes.queries[].group_by
array

The query builder's GROUP BY blocks. Present only for query_builder and tail_query_builder queries, and omitted when not set.

attributes.queries[].having
array

The query builder's HAVING condition blocks. Present only for query_builder and tail_query_builder queries, as an empty array when there are none.

attributes.queries[].order_by
array

The query builder's ORDER BY blocks. Present only for query_builder and tail_query_builder queries, as an empty array when there are none.

attributes.variables
array

The exploration's variables, such as the built-in time, start_time, end_time, and source variables.

attributes.variables[].name
string

The name of the variable, used as {{name}} in queries.

attributes.variables[].variable_type
string

The type of the variable: source, date, datetime, string, number, sql_expression, select_value, boolean, select_with_sql, or select_predefined_sql.

attributes.variables[].values
array

The variable's current values as strings, or an empty array when it has none. For a source variable, these are the IDs of the selected sources.

attributes.variables[].default_values
array

The variable's default values as strings, or an empty array when it has none.

attributes.variables[].sql_definition
string

The SQL query that lists the options of a select_with_sql variable. Omitted when not set.

attributes.variables[].structured_value
object

Additional settings of the variable, such as the selected sources of a source variable in canonicalSourceIds and its services in serviceIds, or the filters of a select_predefined_sql variable. Omitted when not set.

attributes.variables[].allow_multiple_values
boolean

Whether a select_value or select_with_sql variable accepts more than one value at a time.

Example request

cURL
curl --request GET \
     --url "https://telemetry.betterstack.com/api/v2/explorations/123" \
     --header "Authorization: Bearer $TOKEN"


Previous article

List all explorations

Next article

Create an exploration