Usage

Updated at:

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

EndpointPurpose
POST /usage/summaryQuery the usage summary and model and tool details for a workspace, agent, or session
POST /usage/trendPaginate 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:00
  • 2026-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 rangeGranularity
No more than 72 hourshour
More than 72 hours, and the end time is no later than the start time plus 3 calendar months in UTC+8day
All other casesmonth

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.

GranularityAlignment boundary
hourThe top of each hour
day00:00 UTC+8 each day
month00: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:

FieldTypeDescription
totalobjectSummary metrics for the current range
modelsarrayModel details grouped by model_name
toolsarrayTool 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"}
}
unitvalue typeMeaning
tokensint64 / nullNumber of tokens
countint64 / nullNumber of calls
msint64 / nullMilliseconds
rationumber / nullDecimal 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)

FieldUnitDescription
input_tokenstokensNumber of model input tokens
output_tokenstokensNumber of model output tokens
total_tokenstokensSum of input and output tokens; null if either is unknown
cache_read_tokenstokensNumber of input tokens read from cache
cache_creation_tokenstokensNumber of input tokens used to create cache
cache_hit_ratioratiocache_read_tokens / input_tokens. null if input is 0, input is unknown, or cache reads are unknown; rounded to 8 decimal places
model_call_countcountNumber of model calls, counted from recorded model request end events, including successful and failed calls
tool_call_countcountNumber of tool calls, counted at call start, including successful, failed, and unfinished calls
builtin_tool_call_countcountNumber of built-in tool calls
mcp_tool_call_countcountNumber of MCP tool calls
custom_tool_call_countcountNumber of custom tool calls
turnscountNumber of interaction turns, counted from events with role=user
stepscountNumber of execution steps: one step for each model request end and one for each tool call start
interrupt_error_countcountNumber 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_countcountNumber of model call failures
tool_failed_countcountNumber of confirmed tool call failures
runtime_msmsTotal 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)

FieldTypeDescription
models[].model_namestring / nullModel name
models[].usageobjectUsage metrics for the model

models[].usage contains the following metrics:

FieldUnitDescription
input_tokens, output_tokens, total_tokenstokensInput, output, and total tokens for the model; calculation rules are the same as the summary
cache_read_tokens, cache_creation_tokenstokensCache read and cache creation tokens for the model
cache_hit_ratioratioCache hit ratio for the model; calculation rules are the same as the summary
call_countcountNumber of calls to the model
failed_countcountNumber of failed calls to the model

Tool details (tools)

FieldTypeDescription
tools[].sourcestring / nullTool source: builtin (built-in tool), mcp (MCP tool), custom (custom tool); null if unknown
tools[].tool_namestring / nullTool name
tools[].usage.call_countobjectNumber of calls, unit=count
tools[].usage.failed_countobjectNumber 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_at is 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.total and the units of all metrics are still returned, each metric value is null, models and tools are [], and data_updated_at is null. Workspace and agent queries still return query_range.
  • If a trend query has no matching records, an empty points array 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; total does not count toward this limit. When the limit is exceeded, query_limit_exceeded is 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 statusError codeDescription and handling
400invalid_parameterInvalid parameters, including unsupported dimensions, granularity, time format, page size, or malformed request body. Correct the request based on error.message
400invalid_page_tokenThe 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
400query_limit_exceededThe 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
404not_foundThe session does not exist or does not belong to the current account and workspace. Session summary queries only
410page_token_expiredThe page token has expired. Remove page_token and restart from the first page. Trend queries only
429rate_limitBoth usage endpoints share the rate limit for the main account and workspace. Reduce concurrency and retry later
503service_unavailableThe usage query or pagination service is temporarily unavailable. Retry later
500internal_errorInternal service error. Keep request_id for troubleshooting