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
      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. Chart comments API
      4. Dashboard sections API
      5. Dashboard alerts API
      6. Dashboard groups API
    4. Explorations
    5. Alerts API
    6. Connections API
    7. Query API ↗
    8. Usage API ↗
  7. Alternative to
    1. Lightstep

Get a single chart

Retrieves a single chart by its ID from a specific dashboard.

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

URL parameters

dashboard_id
required integer

The unique identifier of the dashboard.

id
required integer

The unique identifier of the chart.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns the chart.

Response body

{
  "data": {
    "id": "567",
    "type": "chart",
    "attributes": {
      "chart_type": "line_chart",
      "name": "CPU Usage",
      "description": "Average CPU usage over time.",
      "x": 0,
      "y": 0,
      "w": 6,
      "h": 4,
      "settings": {
        "unit": "percent",
        "y_axis_scale": "linear"
      },
      "queries": [
        {
          "id": 890,
          "query_type": "sql_expression",
          "source_variable": "source",
          "sql_query": "SELECT {{time}} as time, avg(cpu) as value FROM metrics GROUP BY time"
        }
      ]
    }
  }
}
404

The specified dashboard or chart was not found.

Response attributes

id
string

The ID of the chart.

type
string

Always chart.

attributes.chart_type
string

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

attributes.name
string

The name of the chart.

attributes.description
string or null

The chart's description, or null when not set.

attributes.x
integer

The chart's horizontal position on the 12-column dashboard grid, counted from 0 on the left.

attributes.y
integer

The chart's vertical position on the dashboard grid, counted from 0 at the top.

attributes.w
integer

The chart's width in grid columns.

attributes.h
integer

The chart's height in grid rows.

attributes.settings
object

Chart-specific display settings, such as the unit and axis scale. The keys depend on the chart type.

attributes.queries
array

The chart's queries.

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.

Example request

cURL
curl --request GET \
     --url "https://telemetry.betterstack.com/api/v2/dashboards/1234/charts/567" \
     --header "Authorization: Bearer $TOKEN"


Previous article

List all charts

Next article

Create a chart