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
        1. List all dashboards GET
        2. Get a single dashboard GET
        3. Create a dashboard POST
        4. Update a dashboard PATCH
        5. Remove a dashboard DELETE
        6. Export a dashboard GET
        7. Import a dashboard POST
        8. List templates GET
      2. Charts API
      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 dashboard

Retrieves detailed information for a single dashboard by its ID, including its charts, sections, and variables.

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

URL parameters

id
required string

The unique identifier of the dashboard.

Headers

Authorization
required string

Bearer $TOKEN

200

Returns the dashboard.

Response body

{
  "data": {
    "id": "1234",
    "type": "dashboard",
    "attributes": {
      "team_id": 123456,
      "team_name": "example-team",
      "name": "Sample Dashboard",
      "dashboard_group_id": 789,
      "refresh_interval": 30,
      "date_range_from": "now-3h",
      "date_range_to": "now",
      "created_at": "2025-01-20T15:00:00.000Z",
      "updated_at": "2025-01-21T10:00:00.000Z",
      "source_eligibility_sql": null,
      "variables": [
        {
          "name": "source",
          "variable_type": "source",
          "values": [
            "123"
          ],
          "default_values": [],
          "structured_value": {
            "canonicalSourceIds": [
              "t123456_my_app:metrics"
            ]
          },
          "allow_multiple_values": false
        },
        {
          "name": "environment",
          "variable_type": "string",
          "values": [
            "production"
          ],
          "default_values": [
            "production"
          ],
          "allow_multiple_values": false
        }
      ],
      "charts": [
        {
          "id": 567,
          "chart_type": "line_chart",
          "name": "CPU Usage",
          "x": 0,
          "y": 0,
          "w": 6,
          "h": 4
        }
      ],
      "sections": [
        {
          "id": 890,
          "name": "Key Metrics",
          "y": 0,
          "collapsed": false
        }
      ],
      "has_overlaps": false
    }
  }
}
401

Invalid or missing authentication token.

404

Resource with the provided ID was not found.

Response body

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

Response attributes

id
string

The ID of the dashboard.

type
string

Always dashboard.

attributes.team_id
integer

The ID of the team that owns the dashboard.

attributes.team_name
string

The name of the team that owns the dashboard.

attributes.name
string

The name of the dashboard.

attributes.dashboard_group_id
integer or null

The ID of the dashboard group the dashboard is in, or null when it isn't in a group.

attributes.refresh_interval
integer

How often the dashboard refreshes its charts, in seconds. 0 means it doesn't refresh automatically.

attributes.date_range_from
string

The start of the dashboard's default time range, such as now-3h.

attributes.date_range_to
string

The end of the dashboard's default time range, such as now.

attributes.created_at
string

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

attributes.updated_at
string

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

attributes.source_eligibility_sql
string or null

The SQL condition that decides which sources can be used with the dashboard, or null when not set.

attributes.variables
array

The dashboard's variables, which chart queries reference by name, such as {{source}}.

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.

attributes.charts
array

A summary of each chart on the dashboard, ordered top to bottom, then left to right. The charts endpoints return the full chart.

attributes.charts[].id
integer

The ID of the chart.

attributes.charts[].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.charts[].name
string

The name of the chart.

attributes.charts[].x
integer

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

attributes.charts[].y
integer

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

attributes.charts[].w
integer

The chart's width in grid columns.

attributes.charts[].h
integer

The chart's height in grid rows.

attributes.sections
array

The sections on the dashboard, ordered top to bottom.

attributes.sections[].id
integer

The ID of the section.

attributes.sections[].name
string or null

The section's title, or null when it has none.

attributes.sections[].y
integer

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

attributes.sections[].collapsed
boolean

Whether the section is collapsed.

attributes.has_overlaps
boolean

Whether any charts or sections overlap on the dashboard grid.

Example cURL

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


Previous article

List all dashboards

Next article

Create a dashboard