# Create a chart

Creates a new chart on a specific dashboard.

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

[[path_param]]
name = "dashboard_id"
description = "The unique identifier of the dashboard."
required = true
type = "integer"

[[body_param]]
name = "chart_type"
description = "The type of chart to create (e.g., `line_chart`, `bar_chart`, `table_chart`)."
required = true
type = "string"

[[body_param]]
name = "queries"
description = "An array of one or more query objects. Only `line_chart` supports multiple queries."
required = true
type = "array"

[[body_param]]
name = "name"
description = "The name of the chart."
required = false
type = "string"

[[body_param]]
name = "description"
description = "A description for the chart."
required = false
type = "string"

[[body_param]]
name = "x"
description = "The horizontal position of the chart on the dashboard grid (0-based). If omitted, the chart is auto-placed."
required = false
type = "integer"

[[body_param]]
name = "y"
description = "The vertical position of the chart on the dashboard grid (0-based). If omitted, the chart is auto-placed."
required = false
type = "integer"

[[body_param]]
name = "w"
description = "The width of the chart in grid units."
required = false
type = "integer"
default = "6"

[[body_param]]
name = "h"
description = "The height of the chart in grid units."
required = false
type = "integer"
default = "4"

[[body_param]]
name = "settings"
description = "A JSON object for chart-specific settings (e.g., units, stacking)."
required = false
type = "object"

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

[responses]
[[response]]
status = 201
description = "The chart was created successfully."
body = '''
{
  "data": {
    "id": "568",
    "type": "chart",
    "attributes": {
      "chart_type": "line_chart",
      "name": "New API Chart",
      "description": null,
      "x": 0,
      "y": 4,
      "w": 6,
      "h": 4,
      "settings": {},
      "queries": [
        {
          "id": 789,
          "query_type": "sql_expression",
          "source_variable": "source",
          "sql_query": "SELECT count() FROM {{source}}"
        }
      ]
    }
  }
}
'''
[/responses]

[warning]
If the created chart's position overlaps with existing charts or sections, the layout will be automatically consolidated after a short delay. The response will include a `warnings` field in this case.
[/warning]

## Example request

```shell
[label cURL]
curl --request POST \
  --url https://telemetry.betterstack.com/api/v2/dashboards/1234/charts \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "chart_type": "line_chart",
    "name": "New API Chart",
    "x": 0,
    "y": 4,
    "queries": [
      {
        "query_type": "sql_expression",
        "sql_query": "SELECT {{time}} as time, count(*) as value FROM {{source}} GROUP BY time"
      }
    ]
  }'
```

## Chart and query compatibility

Not all query types are compatible with all chart types. Use this matrix to ensure you are using a valid combination.

| Chart Type | `sql_expression` | `tail_query` | `static_text` | `funnel_query` (read-only) |
|---|:---:|:---:|:---:|:---:|
| `line_chart` | Yes | Yes | - | - |
| `bar_chart` | Yes | Yes | - | - |
| `number_chart` | Yes | Yes | - | - |
| `table_chart` | Yes | - | - | - |
| `pie_chart` | Yes | - | - | - |
| `gauge_chart` | Yes | Yes | - | - |
| `tail_chart` | - | Yes | - | - |
| `static_text_chart` | - | - | Yes | - |
| `text_chart` | Yes | Yes | - | - |
| `scatter_chart` | Yes | - | - | - |
| `heatmap_chart` | Yes | - | - | - |
| `map_chart` | Yes | - | - | - |
| `anomalies_chart` | - | Yes | - | - |
| `funnel_chart` | - | - | - | Yes |

## Queries

Each object in the `queries` array defines a data source for the chart.

- `query_type` - The type of query. Choose one of:
  - `sql_expression` for querying using SQL.
  - `tail_query` for log filtering, similar to Live tail.
  - `static_text` for static markdown text.
- `sql_query` - The SQL query string. Required for `sql_expression`.
- `where_condition` - The filter query for `tail_query`.
- `static_text` - The markdown content for `static_text_chart`.
- `source_variable` - The name of the `source` type variable to use. Defaults to `source`.

## Limitations

- **Read-only query types**: Query types like `query_builder`, `pql_expression`, and `funnel_query` cannot be created or modified via the API as they require client-side compilation to SQL. These may appear in chart configurations or error messages.
- **`funnel_chart`**: This chart type cannot be created via the API because it only accepts `funnel_query`, which is a read-only query type.
- **Multiple queries**: Only `line_chart` supports multiple queries. All other chart types accept only a single query.