List rated usage records

List an account’s rated usage records, applied prices, and net charges.

GET https://billing.moi.matrixorigin.cn/api/v1/billing/accounts/$ACCOUNT_ID/usage-records

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/usage-records?page_size=2" \
  -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.
to	string	No	Exclusive end by record creation time. A date-only value expands to midnight after that date.
timezone	string	No	IANA time zone for date-only values; defaults to UTC.
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.
page_size	integer	No	Page size, 1–100; omitted, nonpositive, or greater than 100 uses 50.
page_token	string	No	Next-page token. Omit for the first request; then use next_page_token from the response.

Successful response

Returns HTTP 200 with the rated usage records matching the filters.

Response example

{
  "items": [
    {
      "rated_usage_record_id": "rated_record_example",
      "usage_event_id": "usage_event_example",
      "billing_account_id": "billing_account_example",
      "billing_account_owner_id": "owner_example",
      "billing_account_display_name": "Example account",
      "meter_code": "meter_example",
      "billing_item_code": "meter_example",
      "billing_item_display_name": "Example usage",
      "unit": "token",
      "price_item_id": "price_example",
      "price_dimension_key": "dimension_example",
      "price_snapshot_json": "{}",
      "quantity": "1000",
      "unit_price_credit": "0.001000000000",
      "gross_credit": "1.000000000000",
      "discount_credit": "0.100000000000",
      "net_credit": "0.900000000000",
      "period": "2026-09",
      "source_period": "2026-09",
      "posting_period": "2026-09",
      "status": "charged",
      "source_request_ids": [
        "request_example"
      ],
      "source_request_count": 1,
      "source_period_start": "2026-09-01T00:00:00Z",
      "source_period_end": "2026-09-01T00:10:00Z",
      "created_at": 1788739200
    }
  ],
  "total": 1,
  "next_page_token": ""
}

Fields

Field	Type	Description
items	array of object	Records returned by this request.
items[].rated_usage_record_id	string	Rated usage record ID.
items[].usage_event_id	string	Source usage event ID.
items[].billing_account_id	string	Billing account ID.
items[].billing_account_owner_id	string	Account owner ID; may be omitted.
items[].billing_account_display_name	string	Account display name; may be omitted.
items[].reservation_id	string	Associated Credit reservation ID, when available.
items[].meter_code	string	Meter code.
items[].billing_item_code	string	Billing item code.
items[].billing_item_display_name	string	Billing item display name.
items[].unit	string	Usage unit.
items[].price_item_id	string	Applied price item ID; may be omitted.
items[].price_dimension_key	string	Price dimension key; may be omitted.
items[].price_snapshot_json	string	Price snapshot used for rating, encoded as a JSON string; may be omitted.
items[].quantity	string	Usage quantity in the billing item’s unit.
items[].unit_price_credit	string	Credit price per usage unit.
items[].gross_credit	string	Gross charge in Credit.
items[].discount_credit	string	Discount in Credit.
items[].net_credit	string	Net charge in Credit.
items[].period	string	Usage period in YYYY-MM format.
items[].source_period	string	Source usage period.
items[].posting_period	string	Posting period.
items[].status	string	Rated usage record status.
items[].source_request_ids	array of string	Source request IDs; may be omitted.
items[].source_request_count	integer	Source request count; may be omitted.
items[].source_period_start	string	Source usage interval start; may be omitted.
items[].source_period_end	string	Source usage interval end; may be omitted.
items[].created_at	integer	Creation time in Unix seconds.
total	integer	Total records matching the filters.
next_page_token	string	Next-page token; an empty string marks the last page.

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

For the next page, set $NEXT_PAGE_TOKEN to next_page_token from the preceding response and retain the same filters. Stop when the token is empty.

curl -X GET \
  "https://billing.moi.matrixorigin.cn/api/v1/billing/accounts/$ACCOUNT_ID/usage-records?page_size=2&page_token=$NEXT_PAGE_TOKEN" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN"

Error response

Missing authentication returns HTTP 401; provide a valid personal access token.

Response example

{
  "code": "unauthenticated",
  "message": "missing bearer token",
  "error": "missing bearer token"
}

Fields

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

Select a posting period

Select a rated usage record and retain its billing_account_id and posting_period. Use these values to list monthly bill usage line items.

Last updated on Sep 15, 2026