Analysis Query

Returns grouped analysis series that can be rendered directly by dashboard charts.

POST /v1/projects/:project_id/analysis/query

Authentication

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

Requires analytics read access.

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the analysis data.

Request Body

This endpoint has its own Analysis request contract: start_time, end_time, measures, metrics, optional filters, subject_type, subject_id, group_by, timezone, and required bucket_size.

timezone defaults to UTC and accepts standard IANA names such as Asia/Shanghai and America/Los_Angeles. Local is not accepted. bucket_size supports positive durations such as 1m, 2h, and 3d, plus the legacy day alias, which normalizes to 1d. Nm and Nh are fixed Unix Epoch-aligned buckets; Nd uses calendar-day boundaries in timezone, anchored to midnight of the date containing start_time.

The maximum range is 31 local calendar days. Minimum buckets are 1m through 1 hour, 15m above 1 hour and below 1 local day, 1h from 1 through 10 local calendar days, 2h above 10 through 21 days, and 4h above 21 days. A smaller bucket returns an analysis_bucket_too_small: error.

{
  "start_time": 1778544000,
  "end_time": 1779148800,
  "timezone": "Asia/Shanghai",
  "bucket_size": "1d",
  "metrics": ["tokens.input"],
  "group_by": ["bucket", "model"],
  "measures": ["quantity", "amount"],
  "limit": 1000
}

For chart use, include bucket in group_by or let the chart layer add it for you. The service always returns grouped series with bucket as the time axis.

Response

{
  "group_by": ["bucket", "model"],
  "measures": ["quantity", "amount"],
  "series": [
    {
      "key": "series_bW9kZWw9Z3B0LTQuMXxtZWFzdXJlPXF1YW50aXR5",
      "label": "model=gpt-4.1 · Quantity",
      "measure": "quantity",
      "dimensions": {
        "model": "gpt-4.1"
      },
      "points": [
        {
          "bucket": "1778580000",
          "value": "1500"
        }
      ]
    }
  ],
  "meta": {
    "timezone": "Asia/Shanghai",
    "bucket_size": "1d",
    "start_time": 1778544000,
    "end_time": 1779148800
  }
}

Notes

• series[].key is stable and chart-safe.
• series[].label is the human-readable series name.
• series[].points[].bucket is the Unix-second instant of the bucket start in meta.timezone.
• meta records the server-normalized timezone, bucket size, and half-open query range.
• Use Aggregate Usage when you want flat grouped rows instead of chart-ready series.