Analysis Charts

Charts are the building blocks of an Analysis board. Each chart persists the exact query payload sent to POST /analysis/query and is re-rendered whenever the dashboard’s time window or live tick fires.

For dashboard charts, the query must resolve to a time series. The service normalizes group_by to start with bucket. If bucket_size is omitted or set to auto, Portal derives it from the active range in the Board timezone: 1m through 1 hour, 15m below one day, 1h from one through ten local calendar days, 2h above ten through 21 days, and 4h above 21 days. Explicit buckets that are too small for the current range are temporarily raised without changing the saved chart configuration.

POST   /v1/projects/:project_id/analysis/boards/:board_id/charts
PUT    /v1/projects/:project_id/analysis/charts/:chart_id
DELETE /v1/projects/:project_id/analysis/charts/:chart_id

Authentication

Write endpoints require analytics:write. Read endpoints require analytics:read.

Create Chart

POST /v1/projects/:project_id/analysis/boards/:board_id/charts

Request Body

Field	Required	Description
board_id	Yes	Must match the board_id path parameter.
chart_id	No	Omit to let the service assign a chr_ prefixed ID.
title	Yes	1–120 characters.
description	No	Optional description.
chart_type	Yes	One of line, area, bar.
position	No	Ordering inside the board. Defaults to the end of the list.
size	No	half (default) shares a row at xl breakpoint. full spans the full row.
subject_type	No	Optional filter applied to every query the chart issues.
bucket_size	No	auto or omitted uses the active time range. Otherwise use a positive duration such as 1m, 2h, or 3d.
filters	No	Map of dimension filters (subject_type=team, etc.).
group_by	No	Up to 4 dimensions.
measures	No	Defaults to ["item_count", "quantity", "amount"] when omitted. Users can keep any subset of those three.
metrics	Yes	At least one and at most 32. Use GET /usage/metrics to discover project metrics.

Response

201 Created with the new chart row.

Update Chart

PUT /v1/projects/:project_id/analysis/charts/:chart_id

Accepts the same body as create. board_id must match the existing chart; otherwise the request returns 400.

Delete Chart

DELETE /v1/projects/:project_id/analysis/charts/:chart_id

Removes the chart from its board. Use the reorder endpoint when you want to reposition the remaining charts.

Errors

Status	Reason
400	Missing metrics, invalid chart_type, group_by > 4, or board mismatch.
404	Chart not found.