Query Usage Trend
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
| Parameter | Required | Type | Description |
|---|---|---|---|
dimension | Yes | string | Only lowercase workspace and agent are supported, case-sensitive. session is not supported |
agent_id | Conditionally required | string | Required when dimension=agent. Specifies one agent. Do not pass for workspace |
agent_version | No | string | Available 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_range | Yes | object | Query time range |
time_range.start_time | Yes | string | Second-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_time | Yes | string | End time, in the same format, must be later than the start time |
granularity | No | string | hour, day, or month; if omitted, selected automatically. Explicit null is not accepted |
page_size | No | integer | Maximum number of periods per page, from 1 to 100, default 100. Explicit null is not accepted |
page_token | No | string | Omit 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
| Field | Type | Description |
|---|---|---|
request_id | string | Request identifier |
data.query_range | object | Actual aligned range for the entire query; the same on every page, not the start and end of the current page |
data.query_range.start_time | string | Start time of the entire query, inclusive, in the +08:00 time zone |
data.query_range.end_time | string | End time of the entire query, exclusive, in the +08:00 time zone |
data.data_updated_at | string / null | Latest 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.granularity | string | Actual granularity used: hour, day, or month |
data.points | array | Periods on the current page, in ascending start_time order; [] if there are no records |
data.points[].start_time | string | Start time of the period, inclusive, in the +08:00 time zone |
data.points[].end_time | string | End time of the period, exclusive, in the +08:00 time zone |
data.points[].usage | object | Usage of the period, including total, models, and tools; see Usage object |
data.has_more | boolean | Whether another page exists |
data.next_page_token | string / null | Cursor 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; removepage_tokenand query the first page again. - Pagination is by complete period, and
page_sizelimits 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 summarytotaldoes 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
0ornull. - If the first query has no records,
points=[],has_more=false, andnext_page_token=nullare returned, while the actualquery_rangeandgranularityare 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.