查询费用趋势

按小时、天或月汇总计费用量的费用，并按计量项、工作区或服务分组。

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

调用前准备

1. 准备计费账户所属用户的有效个人访问令牌。

2. 调用查询当前账户接口，获取目标账户的 ID。

请求参数

将示例中的 $ACCOUNT_ID、$MOI_PERSONAL_ACCESS_TOKEN 替换为实际值。

输入示例

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"

参数说明

参数	类型	是否必填	说明
accountID	string	是	目标账户的 ID，取自“查询当前账户”响应中的 items[].billing_account_id。

查询参数

时间参数使用 RFC 3339 格式或有效的 YYYY-MM-DD 日期。不要使用 10 位 Unix 秒时间戳，否则会返回 HTTP 400。

参数	类型	是否必填	说明
from	string	否	查询开始时间。使用 RFC 3339 格式或有效的 YYYY-MM-DD 日期。传入 10 位 Unix 秒时间戳时返回 HTTP 400。
to	string	否	查询结束时间。使用 RFC 3339 格式或有效的 YYYY-MM-DD 日期。传入 10 位 Unix 秒时间戳时返回 HTTP 400。
timezone	string	否	IANA 时区。省略时使用账户地区的计费时区。
granularity	string	否	时间粒度：hour、day、month，默认 day。
dimension	string	否	分组维度：none（不分组）、meter（计量项）、workspace（工作区）、service（服务），默认 meter。
period	string	否	按入账账期筛选，格式为 YYYY-MM。
meter_code	string	否	按计量项代码筛选。
billing_item_code	string	否	按计费项代码筛选。与 meter_code 同时提供时须匹配同一计量项。
workspace_id	string	否	按用量事件所属工作区筛选。
status	string	否	按用量记录状态筛选。查询已扣费记录时使用 charged。省略时不按状态筛选。
subject_type	string	否	按账户所属主体的类型筛选。
subject_id	string	否	按账户所属主体的 ID 筛选。
q	string	否	搜索计费用量记录 ID、用量事件 ID、计量项代码或事件键，不区分大小写。
search	string	否	q 的别名。仅在 q 为空时生效。

成功响应

响应示例

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

字段说明

字段	类型	说明
items	array of object	费用趋势。
items[].bucket_start	string	统计区间起点，RFC 3339 时间。
items[].bucket_end	string	统计区间终点，不包含该时刻。
items[].bucket_start_unix	integer	统计区间起点，Unix 秒。
items[].bucket_end_unix	integer	统计区间终点，Unix 秒。
items[].dimension	string	聚合维度。
items[].group_key	string	分组标识。
items[].group_label	string	分组显示名称。
items[].meter_code	string	计量项代码。
items[].workspace_id	string	按工作区聚合时的工作区 ID，存在时返回。
items[].service_code	string	按服务聚合时的服务代码，存在时返回。
items[].quantity	string	分组内的用量合计。
items[].gross_credit	string	折扣前费用，单位为 Credit。
items[].discount_credit	string	折扣抵扣，单位为 Credit。
items[].net_credit	string	折扣后费用，单位为 Credit。
items[].source_record_ids	array of string	参与聚合的计费用量记录 ID。
items[].source_record_count	integer	参与聚合的记录数。
total_credit	string	返回各组折扣后费用之和，单位为 Credit。
granularity	string	实际使用的时间粒度。
dimension	string	实际使用的分组维度。
timezone	string	实际使用的 IANA 时区。
from	string	查询开始时间。使用 RFC 3339 格式或有效的 YYYY-MM-DD 日期。传入 10 位 Unix 秒时间戳时返回 HTTP 400。
to	string	查询结束时间。使用 RFC 3339 格式或有效的 YYYY-MM-DD 日期。传入 10 位 Unix 秒时间戳时返回 HTTP 400。

错误响应

时间粒度不受支持时返回 HTTP 400。按参数说明修改时间粒度。

响应示例

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

字段说明

字段	类型	说明
code	string	错误代码。
message	string	错误说明。
error	string	错误说明，内容与 message 相同。

最后更新于 2026 年 10 月 19 日