Query Usage Summary
Query the usage summary for a workspace, agent, or session, including totals and details grouped by model and tool.
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/summary
Retrieves usage for a workspace or agent in a specified time range, or the cumulative usage of a single session since creation. The response includes totals and details grouped by model and by tool.
Request body
| Parameter | Required | Type | Description |
|---|---|---|---|
dimension | Yes | string | Query dimension, case-sensitive. The value must be workspace, agent, or session |
agent_id | Conditionally required | string | Required when dimension=agent. Specifies one agent. Do not pass for other dimensions |
agent_version | No | string | Available only when dimension=agent. Specifies the agent version; 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 |
session_id | Conditionally required | string | Required when dimension=session. Use the ID returned when the session was created; must be a non-empty, non-whitespace-only single string. Do not pass for other dimensions |
time_range | Conditionally required | object | Required for workspace and agent dimensions; not accepted for session |
time_range.start_time | Conditionally required | string | Required when time_range is used. Second-level RFC 3339 string with a time zone, for example 2026-11-02T10:15:30+08:00; seconds can be non-zero and do not need to align to a whole minute |
time_range.end_time | Conditionally required | string | Required when time_range is used. End time, in the same format, must be later than the start time |
granularity | No | string | Available for workspace and agent dimensions. Values are hour, day, and month; if omitted, selected automatically. Affects how the actual query range is aligned. Do not pass for session |
The parameter combinations for the three dimensions are as follows:
| dimension | Scope | Parameters |
|---|---|---|
workspace | Usage of the current workspace | time_range is required. Do not pass agent_id, agent_version, or session_id |
agent | Usage of a specific agent in the current workspace | agent_id and time_range are required. agent_version is optional. Do not pass session_id |
session | Lifetime cumulative usage of a specific session in the current workspace | Pass only dimension and session_id. Do not pass agent filters, time_range, or granularity |
agent_id and session_id must be non-empty single values. time_range and granularity do not accept explicit null. Passing agent filters with the workspace dimension, or time_range or granularity with the session dimension, returns HTTP 400 / invalid_parameter. Time ranges are aligned to UTC+8; for details, see Usage.
This endpoint returns the total and all model and tool details in one response and does not provide pagination. The combined limit for model and tool detail items per request is 100,000; when exceeded, HTTP 400 / query_limit_exceeded is returned instead of truncated results.
Request examples
Query usage of the current workspace
curl -X POST "$AGENTSTUDIO_URL/usage/summary" \
-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"
}'
Query a specific version of an agent
curl -X POST "$AGENTSTUDIO_URL/usage/summary" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dimension": "agent",
"agent_id": "agent_xxx",
"agent_version": "1",
"time_range": {
"start_time": "2026-11-02T10:15:30+08:00",
"end_time": "2026-11-02T14:00:01+08:00"
},
"granularity": "hour"
}'
Query cumulative usage of a session
curl -X POST "$AGENTSTUDIO_URL/usage/summary" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dimension": "session",
"session_id": "sesn_xxx"
}'
Response example
A successful request returns HTTP 200 with top-level fields request_id and data. The following is the summary for the agent request above: the second-level start and end times are aligned by hour to 10:00—15:00 UTC+8. Values are for illustration only.
{
"request_id": "req_summary_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-02T14:10:00+08:00",
"usage": {
"total": {
"input_tokens": {"value": 1000, "unit": "tokens"},
"output_tokens": {"value": 200, "unit": "tokens"},
"total_tokens": {"value": 1200, "unit": "tokens"},
"cache_read_tokens": {"value": 400, "unit": "tokens"},
"cache_creation_tokens": {"value": 100, "unit": "tokens"},
"cache_hit_ratio": {"value": 0.4, "unit": "ratio"},
"model_call_count": {"value": 5, "unit": "count"},
"tool_call_count": {"value": 3, "unit": "count"},
"builtin_tool_call_count": {"value": 0, "unit": "count"},
"mcp_tool_call_count": {"value": 3, "unit": "count"},
"custom_tool_call_count": {"value": 0, "unit": "count"},
"turns": {"value": 2, "unit": "count"},
"steps": {"value": 8, "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": 60000, "unit": "ms"}
},
"models": [
{
"model_name": "qwen-plus",
"usage": {
"input_tokens": {"value": 1000, "unit": "tokens"},
"output_tokens": {"value": 200, "unit": "tokens"},
"total_tokens": {"value": 1200, "unit": "tokens"},
"cache_read_tokens": {"value": 400, "unit": "tokens"},
"cache_creation_tokens": {"value": 100, "unit": "tokens"},
"cache_hit_ratio": {"value": 0.4, "unit": "ratio"},
"call_count": {"value": 5, "unit": "count"},
"failed_count": {"value": 1, "unit": "count"}
}
}
],
"tools": [
{
"source": "mcp",
"tool_name": "web_search",
"usage": {
"call_count": {"value": 3, "unit": "count"},
"failed_count": {"value": 1, "unit": "count"}
}
}
]
}
}
}
Response fields
| Field | Type | Description |
|---|---|---|
request_id | string | Request identifier, useful for troubleshooting |
data | object | Usage query result |
data.query_range | object | Actual query range. Returned only for workspace and agent dimensions; not returned for session |
data.query_range.start_time | string | Aligned start time, inclusive, always in the +08:00 time zone |
data.query_range.end_time | string | Aligned end time, exclusive, always in the +08:00 time zone |
data.data_updated_at | string / null | Latest known update time among the usage records in this response, always in the +08:00 time zone; null if there are no records or the update time is unknown |
data.usage | object | Totals and grouped details |
data.usage.total | object | Summary metrics for the query range; see Summary metrics (total) |
data.usage.models | array | Usage details grouped by model name; [] if there are no details |
data.usage.tools | array | Usage details grouped by tool source and name; [] if there are no details |
Session queries return the same usage structure without query_range or session metadata such as title and status. The service verifies session ownership before querying lifetime cumulative usage. If the session exists but has no statistics yet, each metric value is null and the model and tool detail arrays are empty; the session is not reported as nonexistent.