Get usage trends

Get the current user’s call, token, and cost metrics over time.

GET https://billing.moi.matrixorigin.cn/api/v1/taas/usage-logs/trend

Before you begin

Prepare a personal access token. For creation and management, see Manage personal access tokens.

Results are scoped to data accessible to the current user.

Query parameters

Replace $MOI_PERSONAL_ACCESS_TOKEN in the example with your personal access token.

Request example

curl --get "https://billing.moi.matrixorigin.cn/api/v1/taas/usage-logs/trend" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "granularity=day"

Parameters

Parameter	Type	Required	Description
start_time	integer	No	Start time in nonnegative Unix seconds; must not exceed end_time.
end_time	integer	No	End time in nonnegative Unix seconds.
model_id	string	No	Catalog model object ID.
model_type	string	No	Model type.
requested_model	string	No	Model name submitted in the inference request.
status	string	No	Call status, such as success or failed.
error_type	string	No	Call error category.
caller_ip	string	No	Caller IP address.
token_key_id	string	No	TaaS local token key ID.
token_key_ids	string	No	TaaS local key IDs; repeat the parameter or comma-separate values.
credential_type	string	Required with credential_id	Credential type: taas_token_key, personal_access_token, or service_account_api_key; requires credential_id.
credential_id	string	Required with credential_type	Credential object ID; requires credential_type.
billing_event_id	string	No	Billing usage-event ID.
billing_record_id	string	No	Billing record ID.
pricing_mode	string	No	Pricing mode.
settlement_method	string	No	Settlement method: genesis or ai_service.
enterprise_plan_id	string	No	Enterprise plan ID.
enterprise_contract_no	string	No	Enterprise contract number.
enterprise_plan_model_id	string	No	Enterprise plan model ID.
response_id	string	No	Responses response ID.
conversation_id	string	No	Conversation ID.
ids	string	No	Usage log IDs; repeat the parameter or comma-separate values.
usage_ids	string	No	Alias for ids; values are combined.
provider_id	string	No	Provider ID; results remain scoped to the current user.
granularity	string	No	Bucket granularity: hour or day; defaults to hour.

Successful response

Returns HTTP 200 with call statistics grouped into time buckets.

Response example

{
  "points": [
    {
      "timestamp": 1788710400,
      "time": "2026-09-07T00:00:00Z",
      "calls": 2,
      "total_calls": 2,
      "input_tokens": 12,
      "output_tokens": 8,
      "total_input_tokens": 12,
      "total_output_tokens": 8,
      "total_user_tokens": 20,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "total_cost": "0.0001",
      "total_channel_cost": "0.00005",
      "total_channel_tokens": 20,
      "total_cache_read_tokens": 0,
      "total_cache_creation_tokens": 0
    }
  ],
  "granularity": "day",
  "start_time": 1788710400,
  "end_time": 1788796799,
  "truncated": false
}

Fields

Field	Type	Description
points	array of object	Buckets with data, ordered by time; empty buckets are not filled.
points[].timestamp	integer	Bucket start in Unix seconds.
points[].time	string	Bucket start in UTC, RFC 3339 format.
points[].calls	integer	Call count in this bucket.
points[].total_calls	integer	Alias of calls.
points[].input_tokens	integer	Input tokens.
points[].output_tokens	integer	Output tokens.
points[].total_input_tokens	integer	Alias of input_tokens.
points[].total_output_tokens	integer	Alias of output_tokens.
points[].total_user_tokens	integer	Sum of input, output, cache-read, and cache-creation tokens.
points[].cache_read_tokens	integer	Total cache-read tokens.
points[].cache_creation_tokens	integer	Total cache-creation tokens.
points[].total_cost	string	Total call cost as a decimal string.
points[].total_channel_cost	string	Total cost of associated upstream requests.
points[].total_channel_tokens	integer	Input, output, and cache tokens across associated upstream requests.
points[].total_cache_read_tokens	integer	Alias of cache_read_tokens.
points[].total_cache_creation_tokens	integer	Alias of cache_creation_tokens.
granularity	string	Requested bucket granularity.
start_time	integer	Effective range start, Unix seconds.
end_time	integer	Effective range end, Unix seconds.
truncated	boolean	True when an omitted start or a range exceeding 999 intervals shortens the range.

In field paths, [] denotes each array item.

An omitted or future end time is limited to the current time. When the range exceeds the limit, the most recent interval is retained.

Error response

Response example

{
  "code": 400,
  "message": "start_time must be a non-negative unix timestamp"
}

Fields

Field	Type	Description
code	integer	HTTP error status.
message	string	Error description.

Last updated on Sep 15, 2026