Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. metrics
  4. Ingesting data
    1. Better Stack collector
    2. Vector
    3. OpenTelemetry
    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. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources & collectors
    3. Dashboards
      1. Dashboards API
      2. Charts API
        1. List all charts GET
        2. Get a single chart GET
        3. Create a chart POST
        4. Update a chart PATCH
        5. Remove a chart DELETE
      3. Dashboard sections API
      4. Dashboard alerts API
      5. Dashboard groups API
    4. Explorations
    5. Alerts API
    6. Connections API
    7. Query API ↗
  7. Alternative to
    1. Lightstep

Create a chart

Creates a new chart on a specific dashboard.

POST https://telemetry.betterstack.com/api/v2/dashboards/{dashboard_id}/charts

URL parameters

dashboard_id
required integer

The unique identifier of the dashboard.

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

chart_type
required string

The type of chart to create (e.g., line_chart, bar_chart, table_chart).

queries
required array

An array of one or more query objects. Only line_chart supports multiple queries.

name
string

The name of the chart.

description
string

A description for the chart.

x
integer

The horizontal position of the chart on the dashboard grid (0-based). If omitted, the chart is auto-placed.

y
integer

The vertical position of the chart on the dashboard grid (0-based). If omitted, the chart is auto-placed.

w
6 integer

The width of the chart in grid units.

h
4 integer

The height of the chart in grid units.

settings
object

A JSON object for chart-specific settings (e.g., units, stacking).

201

The chart was created successfully.

Response body

{
  "data": {
    "id": "568",
    "type": "chart",
    "attributes": {
      "chart_type": "line_chart",
      "name": "New API Chart",
      "x": 0,
      "y": 4,
      "w": 6,
      "h": 4,
      "queries": [...]
    }
  }
}

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, similar to Live tail.
    • static_text for static markdown text.
  • sql_query - The SQL query string. Required for sql_expression.
  • where_condition - The filter query for tail_query.
  • static_text - The markdown content for static_text_chart.
  • source_variable - The name of the source type variable to use. Defaults to source.

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

If the created chart's position overlaps with existing charts or sections, the layout will be automatically consolidated after a short delay. The response will include a warnings field in this case.

Example Request

cURL
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/dashboards/1234/charts \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "chart_type": "line_chart",
    "name": "New API Chart",
    "x": 0,
    "y": 4,
    "queries": [
      {
        "query_type": "sql_expression",
        "sql_query": "SELECT {{time}} as time, count(*) as value FROM {{source}} GROUP BY time"
      }
    ]
  }'


Previous article

Get a single chart

Next article

Update a chart