# Create a dashboard

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

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v2/dashboards"
method = "POST"

[[body_param]]
name = "name"
description = "The name of the dashboard."
required = true
type = "string"

[[body_param]]
name = "dashboard_group_id"
description = "The ID of a dashboard group to organize this dashboard."
required = false
type = "integer"

[[body_param]]
name = "refresh_interval"
description = "Refresh interval in seconds. `0` means no refresh."
required = false
type = "integer"
default = "0"

[[body_param]]
name = "date_range_from"
description = "The start of the dashboard's date range."
required = false
type = "string"
default = "now-3h"

[[body_param]]
name = "date_range_to"
description = "The end of the dashboard's date range."
required = false
type = "string"
default = "now"

[[body_param]]
name = "source_eligibility_sql"
description = "An SQL filter determining which sources can be used with this dashboard."
required = false
type = "string"

[[body_param]]
name = "variables"
description = "An array of custom query variable objects. Default variables (`time`, `start_time`, `end_time`, `source`) are created automatically if not provided."
required = false
type = "array"

[[body_param]]
name = "team_name"
description = "Required if using a [global API token](https://betterstack.com/docs/logs/api/getting-started/#get-a-global-api-token) to specify which team should own the resource."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = "The dashboard was created successfully."
body = '''
{
  "data": {
    "id": "12345",
    "type": "dashboard",
    "attributes": {
      "team_id": 123,
      "team_name": "My Team",
      "name": "My Dashboard",
      "dashboard_group_id": null,
      "refresh_interval": 0,
      "date_range_from": "now-3h",
      "date_range_to": "now",
      "source_eligibility_sql": null,
      "created_at": "2026-03-25T10:00:00.000Z",
      "updated_at": "2026-03-25T10:00:00.000Z",
      "variables": [
        {
          "name": "time",
          "variable_type": "datetime",
          "values": [],
          "default_values": []
        },
        {
          "name": "start_time",
          "variable_type": "datetime",
          "values": [],
          "default_values": []
        },
        {
          "name": "end_time",
          "variable_type": "datetime",
          "values": [],
          "default_values": []
        },
        {
          "name": "source",
          "variable_type": "source",
          "values": [],
          "default_values": []
        }
      ],
      "charts": [],
      "sections": [],
      "has_overlaps": false
    }
  }
}
'''

[[response]]
status = 422
description = "Validation failed due to missing required attributes."
body = '''
{
  "errors": "Sorry, you are missing some required attributes",
  "required_attributes": [
    "name"
  ]
}
'''

[[response]]
status = 422
description = "Validation failed due to invalid parameters."
body = '''
{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "name": ["can't be blank"]
  }
}
'''
[/responses]

## Example request

```shell
[label 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"
      }
    ]
  }'
```

## Variables

Each object in the `variables` array defines a new variable. See [Query variables](https://betterstack.com/docs/logs/dashboards/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` and `multi_select_with_sql` types to populate options.