Usage
Query token consumption, model calls, tool calls, and runtime for Managed Agents at the workspace, agent, and session levels.
Overview
Query token consumption, model calls, tool calls, and runtime for Managed Agents. Get summaries by workspace, agent, or session, and view usage changes by hour, UTC+8 calendar day, or calendar month.
Prerequisites
Workspace and API Key configured. For details, see Overview and authentication.
The examples use AGENTSTUDIO_URL for the API base URL and DASHSCOPE_API_KEY for an API Key that can access the workspace; for configuration, see Authentication. For example:
export AGENTSTUDIO_URL="https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio"
Replace {workspace_id} with the workspace ID. Each request queries usage only for the workspace corresponding to the endpoint. The account and workspace are provided by the authentication gateway. Account or workspace fields in the request body cannot override the gateway identity.
Endpoints
| Endpoint | Purpose |
|---|---|
POST /usage/summary | Query the usage summary and model and tool details for a workspace, agent, or session |
POST /usage/trend | Paginate the usage trend for a workspace or agent; each period includes a summary and model and tool details |
Time range and granularity
This section applies to workspace and agent summary and trend queries. Session summaries always query lifetime cumulative usage and do not use a time range or granularity.
Time format
Start and end times are second-level RFC 3339 strings with a time zone. Z and numeric offsets are supported. Seconds can be non-zero and do not need to align to a whole minute, for example:
2026-11-02T10:00:30+08:002026-11-02T02:00:30Z, which represents the same instant as the previous example.
Unix timestamps, strings without a time zone, and fractional seconds are not accepted, for example 2026-11-02T10:00:00.123+08:00. Response times always use +08:00; runtime is still expressed in milliseconds.
Automatic granularity selection
If granularity is omitted, the granularity is selected from the original request range:
| Original range | Granularity |
|---|---|
| No more than 72 hours | hour |
| More than 72 hours, and the end time is no later than the start time plus 3 calendar months in UTC+8 | day |
| All other cases | month |
If granularity is specified explicitly, the specified granularity is used. hour, day, and month are supported.
Actual query range
The service aligns the start time backward and the end time forward to complete periods in UTC+8 (Asia/Shanghai). The actual range is returned in query_range.
| Granularity | Alignment boundary |
|---|---|
hour | The top of each hour |
day | 00:00 UTC+8 each day |
month | 00:00 UTC+8 on the first day of each month; calendar month lengths vary |
For example, an hour query for 10:15:30—14:00:01 UTC+8 covers 10:00:00—15:00:00. If the end time is already on a boundary, it is not extended; for example, 10:00:00—14:00:00 remains unchanged.
All ranges are left-closed and right-open: the start instant is included and the end instant is excluded. To compare a summary with a trend, use the same query conditions and check query_range. Ratio metrics must be recalculated from the summed numerator and denominator; they cannot be added or averaged directly.
Usage object
data.usage in summary responses and data.points[].usage in trend responses share the same structure:
| Field | Type | Description |
|---|---|---|
total | object | Summary metrics for the current range |
models | array | Model details grouped by model_name |
tools | array | Tool details grouped by source and tool_name; tools with the same name but different sources are returned separately |
Metric values and units
Each metric contains value and unit:
{
"input_tokens": {"value": 1000, "unit": "tokens"},
"tool_call_count": {"value": 3, "unit": "count"},
"runtime_ms": {"value": 60000, "unit": "ms"},
"cache_hit_ratio": {"value": 0.4, "unit": "ratio"}
}
| unit | value type | Meaning |
|---|---|---|
tokens | int64 / null | Number of tokens |
count | int64 / null | Number of calls |
ms | int64 / null | Milliseconds |
ratio | number / null | Decimal ratio, for example 0.4 means 40% |
If a metric is unknown, the object and unit are still returned, for example {"value":null,"unit":"tokens"}. A known zero value is returned as 0. Do not treat null as zero.
Summary metrics (total)
| Field | Unit | Description |
|---|---|---|
input_tokens | tokens | Number of model input tokens |
output_tokens | tokens | Number of model output tokens |
total_tokens | tokens | Sum of input and output tokens; null if either is unknown |
cache_read_tokens | tokens | Number of input tokens read from cache |
cache_creation_tokens | tokens | Number of input tokens used to create cache |
cache_hit_ratio | ratio | cache_read_tokens / input_tokens. null if input is 0, input is unknown, or cache reads are unknown; rounded to 8 decimal places |
model_call_count | count | Number of model calls, counted from recorded model request end events, including successful and failed calls |
tool_call_count | count | Number of tool calls, counted at call start, including successful, failed, and unfinished calls |
builtin_tool_call_count | count | Number of built-in tool calls |
mcp_tool_call_count | count | Number of MCP tool calls |
custom_tool_call_count | count | Number of custom tool calls |
turns | count | Number of interaction turns, counted from events with role=user |
steps | count | Number of execution steps: one step for each model request end and one for each tool call start |
interrupt_error_count | count | Number of error events that are not model or tool call failures; model and tool call failures are counted in their respective failure metrics |
model_failed_count | count | Number of model call failures |
tool_failed_count | count | Number of confirmed tool call failures |
runtime_ms | ms | Total duration of settled runtime segments; unsettled segments are not included |
Cache read and cache creation tokens are already part of input usage; do not add them again when calculating total_tokens. total, models, and tools are different views of the same range; do not add the total and the details together.
Model details (models)
| Field | Type | Description |
|---|---|---|
models[].model_name | string / null | Model name |
models[].usage | object | Usage metrics for the model |
models[].usage contains the following metrics:
| Field | Unit | Description |
|---|---|---|
input_tokens, output_tokens, total_tokens | tokens | Input, output, and total tokens for the model; calculation rules are the same as the summary |
cache_read_tokens, cache_creation_tokens | tokens | Cache read and cache creation tokens for the model |
cache_hit_ratio | ratio | Cache hit ratio for the model; calculation rules are the same as the summary |
call_count | count | Number of calls to the model |
failed_count | count | Number of failed calls to the model |
Tool details (tools)
| Field | Type | Description |
|---|---|---|
tools[].source | string / null | Tool source: builtin (built-in tool), mcp (MCP tool), custom (custom tool); null if unknown |
tools[].tool_name | string / null | Tool name |
tools[].usage.call_count | object | Number of calls, unit=count |
tools[].usage.failed_count | object | Number of confirmed call failures, unit=count |
Tool details do not include token or runtime metrics. The summary endpoint does not guarantee the order of the model and tool detail arrays; the trend endpoint returns points in ascending time order. If a model name, tool name, or source is unknown, the detail is still returned and the corresponding field can be null.
Data updates and empty results
- Statistics are updated continuously as usage is processed, so recent calls may not appear yet. Results may be briefly cached; consecutive requests are not guaranteed to reflect the latest statistics immediately.
data_updated_atis the latest known source update time among the records in this result. It does not mean that all data before that time has been processed, and it is not the request time.- If a summary query has no matching records,
usage.totaland the units of all metrics are still returned, each metricvalueisnull,modelsandtoolsare[], anddata_updated_atisnull. Workspace and agent queries still returnquery_range. - If a trend query has no matching records, an empty
pointsarray is returned. Missing periods are not filled with zeros automatically. - Summary and trend both return all model and tool details included in the query; they do not return partial results by Top N or silent truncation. The combined limit for model and tool detail items is 100,000, calculated over the entire query range for summaries and over the current page for trends;
totaldoes not count toward this limit. When the limit is exceeded,query_limit_exceededis returned.
Error responses
Business errors use the following structure. For example, an expired pagination token returns HTTP 410:
{
"type": "error",
"error": {
"code": "page_token_expired",
"message": "page_token has expired; restart pagination from the first page."
},
"request_id": "req_error_example"
}
Authentication and workspace routing errors are returned by the gateway, with top-level request_id, code, and message. For example, an invalid API Key returns HTTP 401:
{
"request_id": "req_auth_error_example",
"code": "InvalidApiKey",
"message": "Invalid API-key provided."
}
For general error responses and workspace routing errors, see Error codes. Both usage endpoints share the request rate limit; when HTTP 429 is returned, reduce concurrency and retry later.
Error codes
| HTTP status | Error code | Description and handling |
|---|---|---|
| 400 | invalid_parameter | Invalid parameters, including unsupported dimensions, granularity, time format, page size, or malformed request body. Correct the request based on error.message |
| 400 | invalid_page_token | The page token is malformed, or the identity, original query conditions, actual granularity, or page_size do not match the token. Use the token returned by the previous page and keep the query conditions unchanged. Trend queries only |
| 400 | query_limit_exceeded | The combined model and tool detail items exceed 100,000: calculated over the entire query range for summaries and over the current page for trends. For summaries, narrow the time range or query a more specific dimension; for trends, reduce page_size or use a finer granularity |
| 404 | not_found | The session does not exist or does not belong to the current account and workspace. Session summary queries only |
| 410 | page_token_expired | The page token has expired. Remove page_token and restart from the first page. Trend queries only |
| 429 | rate_limit | Both usage endpoints share the rate limit for the main account and workspace. Reduce concurrency and retry later |
| 503 | service_unavailable | The usage query or pagination service is temporarily unavailable. Retry later |
| 500 | internal_error | Internal service error. Keep request_id for troubleshooting |