Get grouped usage¶

Aggregate the current user’s usage by user, model, or credential.

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

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/group-by" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "group_by=model" \
  --data-urlencode "page_size=2"

Save the returned next_page_token as $NEXT_PAGE_TOKEN, retain the same filters, and request the next page. Stop when this value is empty or omitted.

curl --get "https://billing.moi.matrixorigin.cn/api/v1/taas/usage-logs/group-by" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "group_by=model" \
  --data-urlencode "page_size=2" \
  --data-urlencode "page_token=$NEXT_PAGE_TOKEN"

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.
`group_by`	string	No	Grouping: user, model, or `token_key`; default user. `token_key` includes all three credential types.
`page_size`	integer	No	Page size; default 100, maximum 1000.
`page_token`	string	No	Next-page token from the previous response; omit for the first request.

Successful response¶

Returns HTTP 200 with call statistics grouped by the selected dimension.

Response example

{
  "items": [
    {
      "group_id": "model_example",
      "group_name": "Example Chat",
      "total_calls": 2,
      "total_input_tokens": 12,
      "total_output_tokens": 8,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "total_cost": "0.0001",
      "total_channel_cost": "0.00005",
      "total_channel_tokens": 20,
      "success_calls": 2,
      "failed_calls": 0,
      "success_rate": 1,
      "success_count": 2,
      "total_cache_read_tokens": 0,
      "total_cache_creation_tokens": 0,
      "avg_latency_ms": 120
    }
  ],
  "total": 1,
  "next_page_token": ""
}

Fields

Field	Type	Description
`items`	array of object	Records on this page.
`items[].group_id`	string	Group identifier.
`items[].group_name`	string	Group display name.
`items[].total_calls`	integer	Total call count.
`items[].total_input_tokens`	integer	Total input tokens.
`items[].total_output_tokens`	integer	Total output tokens.
`items[].cache_read_tokens`	integer	Total cache-read tokens.
`items[].cache_creation_tokens`	integer	Total cache-creation tokens.
`items[].total_cost`	string	Total call cost as a decimal string.
`items[].total_channel_cost`	string	Total cost of associated upstream requests.
`items[].total_channel_tokens`	integer	Input, output, and cache tokens across associated upstream requests.
`items[].success_calls`	integer	Successful call count.
`items[].failed_calls`	integer	Non-successful call count.
`items[].success_rate`	number	Successful calls divided by total calls; 0 when there are no calls.
`items[].success_count`	integer	Alias of `success_calls`.
`items[].total_cache_read_tokens`	integer	Alias of `cache_read_tokens`.
`items[].total_cache_creation_tokens`	integer	Alias of `cache_creation_tokens`.
`items[].avg_latency_ms`	integer	Average `latency` of calls with a positive `latency`, in milliseconds.
`items[].credential`	object	Credential identity when grouped by credential.
`items[].credential.type`	string	Credential type: `taas_token_key`, `personal_access_token`, or `service_account_api_key`.
`items[].credential.id`	string	Credential object ID.
`items[].credential.service_account_id`	string	Service account ID; returned for service-account credentials.
`items[].credential.name`	string	Current credential name, when metadata is available.
`items[].credential.service_account_name`	string	Service account name, when metadata is available.
`total`	integer	Total records matching the filters.
`next_page_token`	string	Next-page token; empty or omitted on the last page.

In field paths, [] denotes each array item.

Error response¶

Response example

{
  "code": 400,
  "message": "provider grouping is only available from admin APIs"
}

Fields

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

Last updated on Sep 15, 2026