Query Usage Summary

Updated at:

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

ParameterRequiredTypeDescription
dimensionYesstringQuery dimension, case-sensitive. The value must be workspace, agent, or session
agent_idConditionally requiredstringRequired when dimension=agent. Specifies one agent. Do not pass for other dimensions
agent_versionNostringAvailable 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_idConditionally requiredstringRequired 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_rangeConditionally requiredobjectRequired for workspace and agent dimensions; not accepted for session
time_range.start_timeConditionally requiredstringRequired 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_timeConditionally requiredstringRequired when time_range is used. End time, in the same format, must be later than the start time
granularityNostringAvailable 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:

dimensionScopeParameters
workspaceUsage of the current workspacetime_range is required. Do not pass agent_id, agent_version, or session_id
agentUsage of a specific agent in the current workspaceagent_id and time_range are required. agent_version is optional. Do not pass session_id
sessionLifetime cumulative usage of a specific session in the current workspacePass 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

FieldTypeDescription
request_idstringRequest identifier, useful for troubleshooting
dataobjectUsage query result
data.query_rangeobjectActual query range. Returned only for workspace and agent dimensions; not returned for session
data.query_range.start_timestringAligned start time, inclusive, always in the +08:00 time zone
data.query_range.end_timestringAligned end time, exclusive, always in the +08:00 time zone
data.data_updated_atstring / nullLatest 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.usageobjectTotals and grouped details
data.usage.totalobjectSummary metrics for the query range; see Summary metrics (total)
data.usage.modelsarrayUsage details grouped by model name; [] if there are no details
data.usage.toolsarrayUsage 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.