Query Usage Trend

Updated at:

Paginate the usage trend for a workspace or agent by hour, UTC+8 calendar day, or calendar month.

Prerequisites

Workspace and API Key configured. For details, see Overview and authentication. For time formats, granularity selection, and range alignment rules, see Usage.

Endpoint

POST /usage/trend

Query usage changes by hour, UTC+8 calendar day, or calendar month. Each period returns totals and model and tool details, and results are paginated in ascending time order.

Request body

ParameterRequiredTypeDescription
dimensionYesstringOnly lowercase workspace and agent are supported, case-sensitive. session is not supported
agent_idConditionally requiredstringRequired when dimension=agent. Specifies one agent. Do not pass for workspace
agent_versionNostringAvailable only when dimension=agent. If omitted or null, all versions are merged; cannot be an empty string or whitespace-only, matched exactly as the original string without trimming leading or trailing spaces
time_rangeYesobjectQuery time range
time_range.start_timeYesstringSecond-level RFC 3339 start time with a time zone; seconds can be non-zero and do not need to align to a whole minute; fractional seconds are not accepted
time_range.end_timeYesstringEnd time, in the same format, must be later than the start time
granularityNostringhour, day, or month; if omitted, selected automatically. Explicit null is not accepted
page_sizeNointegerMaximum number of periods per page, from 1 to 100, default 100. Explicit null is not accepted
page_tokenNostringOmit for the first query. For subsequent pages, pass the previous page's next_page_token unchanged; do not parse or construct it. Explicit null, empty string, whitespace-only, or invalid cursors are not accepted

For the workspace dimension, do not pass agent filter parameters; passing them returns HTTP 400 / invalid_parameter. For the agent dimension, agent_id must be a non-empty single value. All body fields are placed directly in the JSON root object.

Request example

Query the hourly usage trend of the current workspace with second-level start and end times. page_size=1 is set to demonstrate pagination:

curl -X POST "$AGENTSTUDIO_URL/usage/trend" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimension": "workspace",
    "time_range": {
      "start_time": "2026-11-02T10:15:30+08:00",
      "end_time": "2026-11-02T14:00:01+08:00"
    },
    "granularity": "hour",
    "page_size": 1
  }'

To query an agent trend, change dimension to agent and add agent_id; to limit the version, also add agent_version.

Response example

A successful request returns HTTP 200. The request above actually covers 10:00—15:00 UTC+8. The following example assumes that only 10:00—11:00 and 13:00—14:00 have summary records in this range; the first page returns the first period:

{
  "request_id": "req_trend_example",
  "data": {
    "query_range": {
      "start_time": "2026-11-02T10:00:00+08:00",
      "end_time": "2026-11-02T15:00:00+08:00"
    },
    "data_updated_at": "2026-11-02T11:05:00+08:00",
    "granularity": "hour",
    "points": [
      {
        "start_time": "2026-11-02T10:00:00+08:00",
        "end_time": "2026-11-02T11:00:00+08:00",
        "usage": {
          "total": {
            "input_tokens": {"value": 600, "unit": "tokens"},
            "output_tokens": {"value": 120, "unit": "tokens"},
            "total_tokens": {"value": 720, "unit": "tokens"},
            "cache_read_tokens": {"value": 240, "unit": "tokens"},
            "cache_creation_tokens": {"value": 60, "unit": "tokens"},
            "cache_hit_ratio": {"value": 0.4, "unit": "ratio"},
            "model_call_count": {"value": 3, "unit": "count"},
            "tool_call_count": {"value": 2, "unit": "count"},
            "builtin_tool_call_count": {"value": 0, "unit": "count"},
            "mcp_tool_call_count": {"value": 2, "unit": "count"},
            "custom_tool_call_count": {"value": 0, "unit": "count"},
            "turns": {"value": 1, "unit": "count"},
            "steps": {"value": 5, "unit": "count"},
            "interrupt_error_count": {"value": 0, "unit": "count"},
            "model_failed_count": {"value": 1, "unit": "count"},
            "tool_failed_count": {"value": 1, "unit": "count"},
            "runtime_ms": {"value": 36000, "unit": "ms"}
          },
          "models": [
            {
              "model_name": "qwen-plus",
              "usage": {
                "input_tokens": {"value": 600, "unit": "tokens"},
                "output_tokens": {"value": 120, "unit": "tokens"},
                "total_tokens": {"value": 720, "unit": "tokens"},
                "cache_read_tokens": {"value": 240, "unit": "tokens"},
                "cache_creation_tokens": {"value": 60, "unit": "tokens"},
                "cache_hit_ratio": {"value": 0.4, "unit": "ratio"},
                "call_count": {"value": 3, "unit": "count"},
                "failed_count": {"value": 1, "unit": "count"}
              }
            }
          ],
          "tools": [
            {
              "source": "mcp",
              "tool_name": "web_search",
              "usage": {
                "call_count": {"value": 2, "unit": "count"},
                "failed_count": {"value": 1, "unit": "count"}
              }
            }
          ]
        }
      }
    ],
    "has_more": true,
    "next_page_token": "v1_0123456789abcdef0123456789abcdef"
  }
}

Response fields

FieldTypeDescription
request_idstringRequest identifier
data.query_rangeobjectActual aligned range for the entire query; the same on every page, not the start and end of the current page
data.query_range.start_timestringStart time of the entire query, inclusive, in the +08:00 time zone
data.query_range.end_timestringEnd time of the entire query, exclusive, in the +08:00 time zone
data.data_updated_atstring / nullLatest known update time among the usage records returned on the current page; null if there are no records or the update time is unknown. Values may differ between pages
data.granularitystringActual granularity used: hour, day, or month
data.pointsarrayPeriods on the current page, in ascending start_time order; [] if there are no records
data.points[].start_timestringStart time of the period, inclusive, in the +08:00 time zone
data.points[].end_timestringEnd time of the period, exclusive, in the +08:00 time zone
data.points[].usageobjectUsage of the period, including total, models, and tools; see Usage object
data.has_morebooleanWhether another page exists
data.next_page_tokenstring / nullCursor for the next page. A non-empty string when has_more=true; null on the last page

Pagination

Pass the next_page_token returned by the previous page unchanged as page_token. Keep the same main account, workspace, dimension, agent, version, original start and end times, actual granularity, and page_size. Start and end times are compared as the same absolute instant, so equivalent time zone notations can be interchanged; even if the aligned query_range is the same, the original time boundaries cannot be changed.

The following cursor is a format example only. Replace it with the value returned by the previous page in actual calls:

curl -X POST "$AGENTSTUDIO_URL/usage/trend" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimension": "workspace",
    "time_range": {
      "start_time": "2026-11-02T10:15:30+08:00",
      "end_time": "2026-11-02T14:00:01+08:00"
    },
    "granularity": "hour",
    "page_size": 1,
    "page_token": "v1_0123456789abcdef0123456789abcdef"
  }'

In this example, the next page returns usage for 13:00—14:00, with has_more=false and next_page_token=null, ending pagination.

  • Each token is valid for 15 minutes from creation and can be retried within that period; retrying the same token does not extend its validity. An expired token returns HTTP 410 / page_token_expired; remove page_token and query the first page again.
  • Pagination is by complete period, and page_size limits only the number of periods. Model and tool details within a period are returned together; the combined model and tool detail items across all periods on the page are limited to 100,000, and the summary total does not count toward this limit.
  • Only periods with summary records are returned; missing periods are not filled automatically. A period is still returned when its recorded metrics are 0 or null.
  • If the first query has no records, points=[], has_more=false, and next_page_token=null are returned, while the actual query_range and granularity are still included.
  • Statistics may continue to update during pagination, and a token does not lock a data snapshot. The next page starts after the last period of the previous page; data added later to periods that have already been paged through is not returned again on subsequent pages. To refresh, query from the first page again; results may still be briefly cached.

For error codes, see Usage.