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": "source",
          "variable_type": "source",
          "default_values": [
            "123"
          ]
        },
        {
          "name": "log_level",
          "variable_type": "select_value",
          "values": [
            "error",
            "warning",
            "info"
          ],
          "default_values": [
            "error"
          ]
        }
      ]
    }
  }
}

{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "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": 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"]
      }
    ]
  }'

Charts

Single object defining the exploration chart.

• query_type - The type of query. Choose of of:
  • line_chart supports multiple queries.
  • bar_chart
  • pie_chart
  • scatter_chart
  • gauge_chart
  • number_chart
  • heatmap_chart
  • table_chart
  • map_chart
  • text_chart
  • tail_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 of 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.
• default_values - Default values defined in the variable itself.