Export a dashboard

Retrieves the full configuration of a dashboard or a public template as a JSON object. This is useful for backing up dashboards or creating new dashboards via the import endpoint.

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

URL parameters

required string

The unique identifier of the dashboard or template to export.

Headers

Authorization

required string

Bearer $TOKEN

200

Returns the dashboard's exported configuration.

Response body

{
  "id": 12345,
  "name": "Better Stack Collector Dashboard",
  "data": {
    "name": "Better Stack Collector Dashboard",
    "refresh_interval": 30,
    "date_range_from": "now-3h",
    "date_range_to": "now",
    "source_eligibility_sql": null,
    "preset": {
      "id": 67890,
      "name": null,
      "preset_type": "implicit",
      "preset_variables": [
        {
          "name": "service",
          "variable_type": "select_value",
          "values": [
            "web"
          ],
          "default_values": [
            "web",
            "api"
          ],
          "sql_definition": null,
          "structured_value": null,
          "allow_multiple_values": false
        }
      ]
    },
    "charts": [
      {
        "chart_type": "line_chart",
        "name": "CPU Usage",
        "description": null,
        "x": 0,
        "y": 0,
        "w": 6,
        "h": 4,
        "transform_with": "async (existingDataByQuery, newDataByQuery, lastRun) => { return newDataByQuery; }",
        "finalize_with": null,
        "fake_with": null,
        "settings": {
          "unit": "percent",
          "y_axis_scale": "linear"
        },
        "explanation": null,
        "explore_link_url": null,
        "chart_queries": [
          {
            "name": null,
            "query_type": "sql_expression",
            "sql_query": "SELECT {{time}} as time, avg(cpu_usage) as value FROM metrics WHERE service = '{{service}}' GROUP BY time",
            "where_condition": null,
            "static_text": null,
            "x_axis": [],
            "y_axis": null,
            "point_size": null,
            "coordinates": [],
            "filters": null,
            "where": [],
            "group_by": null,
            "having": [],
            "order_by": [],
            "source_variable": "source",
            "promql_query": null,
            "pql_query": null,
            "funnel_query": null,
            "mergeable_split_aggregations": null
          }
        ],
        "chart_alerts": []
      }
    ],
    "sections": [
      {
        "name": "System Metrics",
        "y": 0,
        "collapsed": false,
        "explanation": null
      }
    ]
  }
}

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

integer

The ID of the exported dashboard or template.

name

string

The name of the exported dashboard or template.

data

object

The dashboard's full configuration, which the Import dashboard endpoint accepts as data.

data.name

string

The name of the dashboard.

data.refresh_interval

integer

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

data.date_range_from

string

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

data.date_range_to

string

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

data.source_eligibility_sql

string or null

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

data.preset

object

The preset that holds the dashboard's variables.

data.preset.id

integer

The ID of the preset.

data.preset.name

string or null

The name of the preset, or null when it has none.

data.preset.preset_type

string

The kind of preset, implicit or explicit. A dashboard's own variables live in an implicit preset.

data.preset.preset_variables

array

The dashboard's variables, ordered by when they were created.

data.preset.preset_variables[].name

string

The name of the variable.

data.preset.preset_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.

data.preset.preset_variables[].values

array

The variable's current values. A template export empties them for source, select_with_sql, and select_predefined_sql variables.

data.preset.preset_variables[].default_values

array or null

The variable's default values, or null when it has none.

data.preset.preset_variables[].sql_definition

string or null

The SQL query that lists the options of a select_with_sql variable, or null when not set.

data.preset.preset_variables[].structured_value

object or null

Additional settings of the variable, such as the selected sources and services of a source variable, or null when not set. A template export leaves out the source and service IDs.

data.preset.preset_variables[].allow_multiple_values

boolean

Whether a select_value or select_with_sql variable accepts more than one value at a time.

data.charts

array

The dashboard's charts, ordered by ID.

data.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.

data.charts[].name

string

The name of the chart.

data.charts[].description

string or null

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

data.charts[].x

integer

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

data.charts[].y

integer

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

data.charts[].w

integer

The chart's width in grid columns.

data.charts[].h

integer

The chart's height in grid rows.

data.charts[].transform_with

string or null

A JavaScript function that transforms the query results before the chart renders them, or null when not set.

data.charts[].finalize_with

string or null

A JavaScript function that runs on the data after transform_with, or null when not set.

data.charts[].fake_with

string or null

A JavaScript function that generates sample data for template previews, or null when not set.

data.charts[].settings

object

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

data.charts[].explanation

string or null

An explanation of the chart, or null when not set.

data.charts[].explore_link_url

string or null

A link the chart offers for exploring its data further, or null when not set.

data.charts[].chart_queries

array

The chart's queries, ordered by ID.

data.charts[].chart_queries[].name

string or null

The name of the query, or null when not set.

data.charts[].chart_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.

data.charts[].chart_queries[].sql_query

string or null

The SQL the query runs, or null when the query type doesn't use SQL.

data.charts[].chart_queries[].where_condition

string or null

The filter of a tail_query or tail_query_builder query, or null.

data.charts[].chart_queries[].static_text

string or null

The Markdown content of a static_text query, or null.

data.charts[].chart_queries[].x_axis

array

The query builder's X axis blocks, or an empty array when not used.

data.charts[].chart_queries[].y_axis

array or null

The query builder's Y axis blocks, or null when not used.

data.charts[].chart_queries[].point_size

array or null

The query builder's point size blocks, or null when not used.

data.charts[].chart_queries[].coordinates

array

The query builder's coordinate blocks, or an empty array when not used.

data.charts[].chart_queries[].filters

array or null

The query builder's filter blocks, or null when not used.

data.charts[].chart_queries[].where

array

The query builder's WHERE condition blocks, or an empty array when not used.

data.charts[].chart_queries[].group_by

array or null

The query builder's GROUP BY blocks, or null when not used.

data.charts[].chart_queries[].having

array

The query builder's HAVING condition blocks, or an empty array when not used.

data.charts[].chart_queries[].order_by

array

The query builder's ORDER BY blocks, or an empty array when not used.

data.charts[].chart_queries[].source_variable

string or null

The sources the query reads, either the name of a source variable such as source or a source: reference to specific sources, or null when not set.

data.charts[].chart_queries[].promql_query

string or null

The PromQL of a PromQL query, or null.

data.charts[].chart_queries[].pql_query

string or null

The PQL of a pql_expression query, or null.

data.charts[].chart_queries[].funnel_query

object or null

The funnel definition of a funnel_query query, or null.

data.charts[].chart_queries[].mergeable_split_aggregations

object or null

Maps result columns to sum, min, or max so the query can run in parts and merge the results, or null when not set.

data.charts[].chart_alerts

array

The chart's alerts, ordered by ID, each with the alert's configuration as the Import dashboard endpoint accepts it, with escalation_target as a string. A template export sets every escalation_target to current_team.

data.sections

array

The dashboard's sections, ordered by ID.

data.sections[].name

string or null

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

data.sections[].y

integer

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

data.sections[].collapsed

boolean

Whether the section is collapsed.

data.sections[].explanation

string or null

An explanation of the section, or null when not set.

Explore documentation

Example cURL

On this page

Explore documentation

Export a dashboard

Example cURL

On this page

Please accept cookies