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 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.

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",
          "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 in a single transaction.

Errors

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