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
      2. Charts API
      3. Dashboard sections API
        1. List all sections GET
        2. Get a single section GET
        3. Create a section POST
        4. Update a section PATCH
        5. Remove a section DELETE
      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 section

Creates a new section on a specific dashboard.

POST https://telemetry.betterstack.com/api/v2/dashboards/{dashboard_id}/sections

URL parameters

dashboard_id
required integer

The unique identifier of the dashboard.

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

name
required string

The name of the section.

y
integer

The vertical position of the section on the dashboard grid. If omitted, it's placed below all existing items.

collapsed
false boolean

Whether the section should be collapsed by default.

201

The section was created successfully.

Response body

{
  "data": {
    "id": "891",
    "type": "section",
    "attributes": {
      "name": "New Section",
      "y": 10,
      "collapsed": false
    }
  }
}
422

Validation failed due to missing required attributes.

Response body

{
  "errors": "Sorry, you are missing some required attributes",
  "required_attributes": [
    "name"
  ]
}

If the new section's position overlaps with existing items, the layout will be automatically consolidated after a short delay.

Example request

cURL
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/dashboards/1234/sections \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "New Section",
    "y": 10
  }'


Previous article

Get a single dashboard section

Next article

Update a dashboard section