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

Creates a new dashboard, including its variables and other properties.

POST https://telemetry.betterstack.com/api/v2/dashboards

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

name
required string

The name of the dashboard.

dashboard_group_id
integer

The ID of a dashboard group to organize this dashboard.

refresh_interval
0 integer

Refresh interval in seconds. 0 means no refresh.

date_range_from
now-3h string

The start of the dashboard's date range.

date_range_to
now string

The end of the dashboard's date range.

source_eligibility_sql
string

An SQL filter determining which sources can be used with this dashboard.

variables
array

An array of custom query variable objects. Default variables (time, start_time, end_time, source) are created automatically if not provided.

team_name
string

Required if using a global API token to specify which team should own the resource.

201

The dashboard was created successfully.

Response body

{
  "data": {
    "id": "1234",
    "type": "dashboard",
    "attributes": {
      "name": "New API Dashboard",
      "dashboard_group_id": 789,
      "refresh_interval": 60,
      "date_range_from": "now-1h",
      "date_range_to": "now",
      "variables": [
        {
          "name": "environment",
          "variable_type": "string",
          "values": [
            "production"
          ],
          "default_values": [
            "production"
          ]
        }
      ]
    }
  }
}
422

Validation failed due to invalid parameters.

Response body

{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "name": [
      "can't be blank"
    ]
  }
}

Variables

Each object in the variables array defines a new variable. See Query variables for details.

  • name - Name of the variable, without the {{}}.
  • variable_type - Type of the variable.
  • values - An array of values for the variable.
  • default_values - An array of default values for the variable.
  • sql_definition - Required for select_with_sql type to populate options.

Example Request

cURL
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/dashboards \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "New API Dashboard",
    "dashboard_group_id": 789,
    "refresh_interval": 60,
    "date_range_from": "now-1h",
    "date_range_to": "now",
    "variables": [
      {
        "name": "environment",
        "variable_type": "string",
        "values": ["production"],
        "default_values": ["production"]
      },
      {
        "name": "service",
        "variable_type": "select_with_sql",
        "sql_definition": "SELECT DISTINCT service FROM logs"
      }
    ]
  }'


Previous article

Get a single dashboard

Next article

Update a dashboard