Usage

Usage 接口为 Console 用量页提供数据，按当前鉴权用户/API Key/Project 上下文聚合。通过 SeaCloud Web 网关访问时，登录用户使用：

https://cloud.seaart.ai/api/sandbox/v1/sandboxes/usage/...

后端服务通过 sandbox gateway 使用：

https://sandbox-service.real-cloud.seaart.ai/api/v1/sandbox/sandboxes/usage/...

汇总

GET /sandboxes/usage/summary

Query：

Query	说明
`period`	`today` 或 `current_month`，默认 `current_month`。
`start_time` / `end_time`	可选显式 Unix 毫秒窗口；兼容 Unix 秒。
`start_at` / `end_at`	`start_time` / `end_time` 的可选别名。
`template_id`	可选模板过滤。为空或 `all` 表示全部模板。

响应包含 vcpu_hours、ram_gb_hours、storage_capacity_gb、running_sandboxes、data_transfer_gb 和 usage_costs_usd。响应中的 start_time 和 end_time 均为 Unix 毫秒。

storage_capacity_gb 表示当前 paused 沙箱的存储已用量，单位 GiB。新暂停的沙箱优先使用 pause 时采样到的 diskUsed；旧数据或没有采样结果时，会回退到配置存储容量，避免历史存储计费中断。

运行时趋势

GET /sandboxes/usage/runtime/vcpu-hours
GET /sandboxes/usage/runtime/ram-hours
GET /sandboxes/usage/runtime/running-sandboxes
GET /sandboxes/usage/runtime/data-transfer

Query：

Query	必填	说明
`cycle_type`	是	`minute` 或 `day`。
`start_time`	是	Unix 毫秒；兼容 Unix 秒。
`end_time`	是	Unix 毫秒；兼容 Unix 秒。
`template_id`	否	模板过滤。为空或 `all` 表示全部模板。

cycle_type=minute 最多查询 24 小时窗口；cycle_type=day 支持 1 到 31 天范围。

示例：

curl 'https://cloud.seaart.ai/api/sandbox/v1/sandboxes/usage/runtime/vcpu-hours?cycle_type=minute&start_time=1781020800000&end_time=1781107199999' \
  -H 'accept: application/json' \
  -H 'x-brand: Seacloud' \
  -b 'auth_token=<auth_token>; refresh_token=<refresh_token>; is_logged_in=true; seacloud-authenticated=1'

响应：

{
  "cycle_type": "minute",
  "start_time": 1781020800000,
  "end_time": 1781107199000,
  "current_value": 1.2619,
  "current_unit": "hours",
  "points": [
    { "timestamp": 1781081760000, "value": "0.0333" }
  ]
}

图表数据来自 points。该接口不返回 timeline。

存储

GET /sandboxes/usage/storage/realtime
GET /sandboxes/usage/storage/stats

storage/realtime 返回：

{
  "storage_mib": "0",
  "free_storage_mib": "10240"
}

storage/stats 使用 cycle_type=hour|day、start_time 和 end_time。start_time 和 end_time 推荐传 Unix 毫秒，兼容 Unix 秒。cycle_type=hour 最多查询 24 小时窗口。响应时间戳为 Unix 毫秒。

两个存储接口返回的都是当前 paused 沙箱的存储已用量，单位 MiB，不代表 running 期间的临时磁盘占用。存储仅在沙箱处于 paused 状态时计费。

费用

GET /sandboxes/usage/costs

Query：

Query	说明
`month`	可选 `YYYY-MM`，默认当前 UTC 月。
`template_id`	可选模板过滤。

响应包含 cycle_type=day、month、current_value_usd 和按天排列的 usages[]。每天的 usage item 会包含 ram、vcpu、storage 原始用量计数，但当前 current_value_usd 和 amount 只基于运行时 CPU、运行时 RAM 和网络流量计算。Paused 存储使用量通过 storage 字段和 storage usage records 单独暴露。