Get cost trends

Aggregate rated usage charges by hour, day, or month and group them by meter, workspace, or service.

GET https://billing.moi.matrixorigin.cn/api/v1/billing/accounts/$ACCOUNT_ID/cost-trends

Before you begin

1. Prepare a valid personal access token for the account owner.

2. Call List current accounts to obtain the target account’s ID.

Request example

Replace $MOI_PERSONAL_ACCESS_TOKEN and $ACCOUNT_ID in the example with your personal access token and the selected account’s ID.

curl -X GET \
  "https://billing.moi.matrixorigin.cn/api/v1/billing/accounts/$ACCOUNT_ID/cost-trends?granularity=month&dimension=meter" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN"

Path parameters

Parameter	Type	Required	Description
accountID	string	Yes	Target account ID from items[].billing_account_id in the List current accounts response.

Query parameters

Parameter	Type	Required	Description
from	string	No	Inclusive start by record creation time; accepts RFC 3339, YYYY-MM-DD, or Unix seconds as a string. Defaults to the start of the last 30 days, including today.
to	string	No	Exclusive end by record creation time. A date-only value expands to midnight after that date. Defaults to tomorrow at midnight in the billing time zone.
timezone	string	No	IANA time zone; defaults to the billing time zone for the account region.
granularity	string	No	Time granularity: hour, day, or month; defaults to day.
dimension	string	No	Grouping dimension: none, meter, workspace, or service; defaults to meter.
period	string	No	Filter by posting period in YYYY-MM format.
meter_code	string	No	Filter by meter code.
billing_item_code	string	No	Filter by billing item code; when combined with meter_code, both must match the same meter.
workspace_id	string	No	Filter by the workspace of the usage event.
status	string	No	Filter by usage record status; use charged for charged records. Omitted means no status filter.
subject_type	string	No	Filter by account owner type.
subject_id	string	No	Filter by account owner ID.
q	string	No	Case-insensitive search over rated record ID, usage event ID, meter code, or event key.
search	string	No	Alias for q, used only when q is empty.

Successful response

Returns HTTP 200 with cost trends grouped by time and the selected dimension.

Response example

{
  "items": [
    {
      "bucket_start": "2026-09-01T00:00:00+08:00",
      "bucket_end": "2026-10-01T00:00:00+08:00",
      "bucket_start_unix": 1788192000,
      "bucket_end_unix": 1790784000,
      "dimension": "meter",
      "group_key": "meter_example",
      "group_label": "Example usage",
      "meter_code": "meter_example",
      "quantity": "1000",
      "gross_credit": "1.000000000000",
      "discount_credit": "0.100000000000",
      "net_credit": "0.900000000000",
      "source_record_ids": [
        "rated_record_example"
      ],
      "source_record_count": 1
    }
  ],
  "total_credit": "0.900000000000",
  "granularity": "month",
  "dimension": "meter",
  "timezone": "Asia/Shanghai",
  "from": "2026-09-01T00:00:00+08:00",
  "to": "2026-10-01T00:00:00+08:00"
}

Fields

Field	Type	Description
items	array of object	Cost trend results.
items[].bucket_start	string	Bucket start in RFC 3339 format.
items[].bucket_end	string	Exclusive bucket end.
items[].bucket_start_unix	integer	Bucket start in Unix seconds.
items[].bucket_end_unix	integer	Bucket end in Unix seconds.
items[].dimension	string	Aggregation dimension.
items[].group_key	string	Group identifier.
items[].group_label	string	Group label.
items[].meter_code	string	Meter code.
items[].workspace_id	string	Workspace ID for workspace grouping, when available.
items[].service_code	string	Service code for service grouping, when available.
items[].quantity	string	Sum of usage quantities in the group.
items[].gross_credit	string	Gross charge in Credit.
items[].discount_credit	string	Discount in Credit.
items[].net_credit	string	Net charge in Credit.
items[].source_record_ids	array of string	Rated usage record IDs included in the aggregate.
items[].source_record_count	integer	Number of records included in the aggregate.
total_credit	string	Sum of returned net charges in Credit.
granularity	string	Applied time granularity.
dimension	string	Applied grouping dimension.
timezone	string	Applied IANA time zone.
from	string	Inclusive query start.
to	string	Exclusive query end.

In field paths, [] denotes each array item. For example, items[].bucket_start refers to the corresponding field in each item.

Error response

An unsupported time granularity returns HTTP 400; correct the query parameters.

Response example

{
  "code": "invalid_request",
  "message": "invalid request",
  "error": "invalid request"
}

Fields

Field	Type	Description
code	string	Error code.
message	string	Error message.
error	string	Compatibility error message, with the same content as message.

Last updated on Sep 15, 2026