Usage

Usage APIs power the Console usage pages. They aggregate by the authenticated user/API key/project context. Through the SeaCloud web gateway, logged-in users can query:

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

Through the sandbox gateway, backend services use:

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

Summary

GET /sandboxes/usage/summary

Query:

Query	Description
`period`	`today` or `current_month`; default is `current_month`.
`start_time` / `end_time`	Optional explicit Unix millisecond window. Unix seconds are accepted for compatibility.
`start_at` / `end_at`	Optional aliases for `start_time` / `end_time`.
`template_id`	Optional template filter. Empty or `all` means all templates.

Response includes vcpu_hours, ram_gb_hours, storage_capacity_gb, running_sandboxes, data_transfer_gb, and usage_costs_usd. Response start_time and end_time are Unix milliseconds.

storage_capacity_gb is the current paused-sandbox storage usage in GiB. For new paused sandboxes it uses the measured diskUsed sample captured during pause; for older records without a disk sample, it falls back to configured storage size so historical storage billing remains continuous.

Runtime Trends

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	Required	Description
`cycle_type`	yes	`minute` or `day`.
`start_time`	yes	Unix milliseconds. Unix seconds are accepted for compatibility.
`end_time`	yes	Unix milliseconds. Unix seconds are accepted for compatibility.
`template_id`	no	Template filter. Empty or `all` means all templates.

cycle_type=minute can query up to a 24 hour window. cycle_type=day supports a 1 to 31 day range.

Example:

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'

Response:

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

Chart data comes from points. This endpoint does not return timeline.

Storage

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

storage/realtime returns:

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

storage/stats uses cycle_type=hour|day, start_time, and end_time. Use Unix milliseconds for start_time and end_time; Unix seconds are accepted for compatibility. For cycle_type=hour, the maximum window is 24 hours. Response timestamps are Unix milliseconds.

Both storage endpoints report current paused-sandbox storage usage in MiB, not runtime temporary disk usage. Storage billing applies only while sandboxes are paused.

Costs

GET /sandboxes/usage/costs

Query:

Query	Description
`month`	Optional `YYYY-MM`; default is the current UTC month.
`template_id`	Optional template filter.

Response contains cycle_type=day, month, current_value_usd, and daily usages[]. Each daily usage item includes ram, vcpu, and storage raw usage counters, but current_value_usd and amount are currently computed from runtime CPU, runtime RAM, and data transfer. Paused storage usage is reported separately through the storage fields and storage usage records.