Create an exploration

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

{
  "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": "time",
          "variable_type": "datetime",
          "default_values": []
        },
        {
          "name": "start_time",
          "variable_type": "datetime",
          "default_values": []
        },
        {
          "name": "end_time",
          "variable_type": "datetime",
          "default_values": []
        },
        {
          "name": "source",
          "variable_type": "source",
          "default_values": [
            "123"
          ]
        }
      ]
    }
  }
}

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

Example request

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": null,
    "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\nFROM {{source}}\nWHERE time BETWEEN {{start_time}} AND {{end_time}}\n  [[ AND JSONExtractString(raw, '\''level'\'') = {{level}} ]]\nGROUP BY time",
        "source_variable": "source"
      }
    ],
    "variables": [
      {
        "name": "source",
        "variable_type": "source",
        "default_values": ["123"]
      },
      {
        "name": "level",
        "variable_type": "multi_select_with_sql",
        "values": [],
        "default_values": [],
        "sql_definition": "JSONExtractString(raw, '\''level'\'')"
      }
    ]
  }'

Chart and query compatibility

Not all query types are compatible with all chart types. Use this matrix to ensure you are using a valid combination.

Charts

Single object defining the exploration chart.

• chart_type - The type of chart. Choose one of:
  • line_chart - Only line_chart supports multiple queries. All other chart types accept only a single query.
  • bar_chart
  • pie_chart
  • scatter_chart
  • gauge_chart
  • number_chart
  • heatmap_chart
  • table_chart
  • map_chart
  • text_chart
  • tail_chart
  • anomalies_chart
  • static_text_chart
• description - detailed explanation shown as a tooltip.
• settings - JSON used for chart-specific settings such as customizing units.

Queries

Each object in the queries array defines a data source for the chart.

• query_type - The type of query. Choose one of:
  • sql_expression for querying using SQL.
  • tail_query for Log filtering query, similar to Live tail.
  • static_text for static markdown text.
• sql_query - The SQL query string. Required for sql_expression type.
• source_variable - The name of the source type variable to use for this query. Defaults to source, but can also point to different sources using source:table_name.
• where_condition - The query string for filtering. Required for tail_query type.
• static_text - The markdown content. Required for static_text type.

Variables

Each object in the variables array defines a new variable. See Query variables for details.

Default variables (time, start_time, end_time, source) are created automatically.

• name - Name of the variable, without the {{}}.
• variable_type - Type of the variable, one of the following:
• values - Values currently saved in the preset.
  • source is a data source reference, values are source IDs.
  • string
  • number
  • date
  • datetime
  • boolean
  • sql_expression for raw SQL expressions, added to the query without escaping.
  • select_value
  • select_with_sql requires sql_definition parameter.
  • multi_select_with_sql requires sql_definition parameter.
• default_values - Default values defined in the variable itself.