The usage rollup endpoint aggregates metered usage across sandboxes and computers, grouped by an identifier of your choice. Use it to build per-user billing dashboards, enforce spend policies, or attribute costs to projects.
Base path: /api/v1/usage
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/usage | Aggregate usage for a period |
Get Usage Rollup
GET /api/v1/usage
Auth
Authorization: Bearer msk_...Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
group_by | string | No | external_user_id | Dimension to aggregate by |
period | string | No | 30d | Predefined period or custom |
start | string | No | - | ISO 8601 start (required when period=custom) |
end | string | No | - | ISO 8601 end (required when period=custom) |
group_by values:
| Value | Description |
|---|---|
external_user_id | Group by the external_user_id you set on sandboxes |
external_project_id | Group by external_project_id |
workspace_id | Group by MIOSA workspace |
period values:
| Value | Description |
|---|---|
7d | Last 7 days |
30d | Last 30 days |
mtd | Month-to-date (calendar month, resets on the 1st) |
custom | Arbitrary range - requires start and end |
Response - 200 OK
{
"period_start": "2026-04-26T00:00:00Z",
"period_end": "2026-05-26T00:00:00Z",
"results": [
{
"external_user_id": "user_clinic_42",
"sandbox_seconds": 14400,
"computer_seconds": 0,
"storage_gb_hours": 2.5,
"credit_cents": 312
},
{
"external_user_id": "user_clinic_99",
"sandbox_seconds": 3600,
"computer_seconds": 7200,
"storage_gb_hours": 0.0,
"credit_cents": 108
}
]
}| Field | Type | Description |
|---|---|---|
period_start | string | ISO 8601 start of aggregation window |
period_end | string | ISO 8601 end of aggregation window |
results[].{group_by} | string | Value of the grouping dimension |
results[].sandbox_seconds | number | vCPU-seconds used by sandboxes |
results[].computer_seconds | number | vCPU-seconds used by computers |
results[].storage_gb_hours | number | GiB-hours of attached storage |
results[].credit_cents | number | Total cost in platform credit cents |
Results are ordered by credit_cents descending.
Errors
| Status | Code | Cause |
|---|---|---|
| 422 | invalid group_by | group_by is not one of the accepted values |
| 422 | invalid period | period is not one of the accepted values |
| 422 | invalid_custom_range | start or end is missing or not valid ISO 8601 when period=custom |