Skip to main content

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

dimension string (必选)Only lowercase workspace and agent are supported, case-sensitive. session is not supportedagent_id string (条件必填)Required when dimension=agent. Specifies one agent. Do not pass for workspaceagent_version 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 spacestime_range object (必选)Query time rangetime_range.start_time 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 acceptedtime_range.end_time string (必选)End time, in the same format, must be later than the start timegranularity string (可选)hour, day, or month; if omitted, selected automatically. Explicit null is not acceptedpage_size integer (可选)Maximum number of periods per page, from 1 to 100, default 100. Explicit null is not acceptedpage_token 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 acceptedFor 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 fields

request_id stringRequest identifierdata.query_range objectActual aligned range for the entire query; the same on every page, not the start and end of the current pagedata.query_range.start_time stringStart time of the entire query, inclusive, in the +08:00 time zonedata.query_range.end_time stringEnd time of the entire query, exclusive, in the +08:00 time zonedata.data_updated_at string / nullLatest 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 pagesdata.granularity stringActual granularity used: hour, day, or monthdata.points arrayPeriods on the current page, in ascending start_time order; [] if there are no recordsdata.points[].start_time stringStart time of the period, inclusive, in the +08:00 time zonedata.points[].end_time stringEnd time of the period, exclusive, in the +08:00 time zonedata.points[].usage objectUsage of the period, including total, models, and tools; see Usage objectdata.has_more booleanWhether another page existsdata.next_page_token string / nullCursor for the next page. A non-empty string when has_more=true; null on the last page

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"
  }
}

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; remove page_token and query the first page again.
  • Pagination is by complete period, and page_size limits 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 summary total does 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 0 or null.
  • If the first query has no records, points=[], has_more=false, and next_page_token=null are returned, while the actual query_range and granularity are 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.