Analysis Boards

Custom Analysis dashboards let Portal users compose boards of charts driven by POST /analysis/query. Each board groups 1..N charts; charts persist their query payload and custom layout against the project and refresh on a configured time window or live tick.

GET    /v1/projects/:project_id/analysis/boards
POST   /v1/projects/:project_id/analysis/boards
PUT    /v1/projects/:project_id/analysis/boards/:board_id
DELETE /v1/projects/:project_id/analysis/boards/:board_id
PUT    /v1/projects/:project_id/analysis/boards/:board_id/order

Authentication

Authorization: Bearer <api-key>
Content-Type: application/json

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

List Boards

GET /v1/projects/:project_id/analysis/boards

Returns every board in the project together with its ordered charts.

The request body is empty. There are no query parameters. Chart width and height, when present, describe its saved custom dimensions; see Save Chart Layout.

Response

{
  "boards": [
    {
      "board": {
        "report_id": "brd_5d8c...",
        "name": "Token overview",
        "description": "All metrics rolled up by team",
        "timezone": "Asia/Shanghai",
        "default_time_range_seconds": 900,
        "created_at": 1735660800,
        "updated_at": 1735664400
      },
      "charts": [
        {
          "chart_id": "chr_a91f...",
          "board_id": "brd_5d8c...",
          "name": "Tokens by model",
          "chart_type": "line",
          "position": 0,
          "size": "half",
          "width": 5,
          "height": 7,
          "subject_type": "team",
          "bucket_size": "5m",
          "filters": { "metric": "tokens.input" },
          "group_by": ["bucket"],
          "measures": ["item_count", "quantity", "amount"],
          "metrics": ["tokens.input"]
        }
      ]
    }
  ]
}

Create Board

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

Request Body

Field	Required	Description
name	Yes	Board name. 1–80 characters.
description	No	Free-form description.
timezone	No	Standard IANA timezone. Defaults to UTC; Local is rejected.
default_time_range_seconds	No	Time window applied when the board becomes active. One of 300, 900, 3600, 86400, 604800, 2592000.

Response

201 Created with the new UsageReport row (kind: "board").

Update Board

PUT /v1/projects/:project_id/analysis/boards/:board_id

Provide any subset of name, description, timezone, or default_time_range_seconds. Send description: "" to clear the description. An explicit timezone update must be a non-empty standard IANA timezone. Returns the updated board.

Delete Board

DELETE /v1/projects/:project_id/analysis/boards/:board_id

Deletes the board and every chart it owns.

Reorder Charts

PUT /v1/projects/:project_id/analysis/boards/:board_id/order

{
  "order": [
    { "chart_id": "chr_a91f...", "position": 0, "size": "half" },
    { "chart_id": "chr_42bc...", "position": 1, "size": "full" }
  ]
}

Every chart_id must belong to the board. The service persists the new positions and custom dimensions in a single transaction. See Save Chart Layout for the complete request and response contract, including width and height.

Errors

Status	Reason
400	Invalid name, description length, or time range.
404	Board not found for this tenant / project.