Usage
AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Scope: read:sandboxes
id*stringExternal sandbox id
Live usage snapshot from the owning runner
application/json- response
Response for GET /sandboxes/{id}/usage. Field order is alphabetical to keep the
wire bytes identical to the former serde_json::json! construction.
id*stringThe requested external sandbox id, echoed back.
runner_id*stringRunner currently hosting the sandbox.
source*stringAlways live (the runner's current snapshot, not the collector).
usage*unknownThe runner's per-sandbox usage document (free-form; runner-defined).
curl -X GET 'https://example.com/sandboxes/string/usage'{ "id": "string", "runner_id": "string", "source": "string", "usage": null}AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Scope: read:sandboxes
id*stringExternal sandbox id
from?stringRFC3339 window start. Default: 24h before to. Unparseable values fall
back to the default.
to?stringRFC3339 window end (exclusive). Default: now.
resolution?string"m" (minute periods, default) | "h" (hourly).
Usage time series (or available: false when the collector DB is not configured)
application/json- response
Response for GET /sandboxes/{id}/usage/history. Field order is alphabetical to
keep the wire bytes identical to the former serde_json::json! construction.
available*booleanFalse when the usage collector DB is not configured (graceful empty
state) — periods is then empty and resolution absent.
periods*array<>resolution?|Effective resolution: "m" | "h". Absent when available is false.
sandbox_id*stringThe requested external sandbox id, echoed back.
curl -X GET 'https://example.com/sandboxes/string/usage/history'{ "available": true, "periods": [ { "cpu_core_s": 0.1, "disk_used": 0, "duration_ms": 0, "io_r_bytes": 0, "io_w_bytes": 0, "mem_byte_s": 0.1, "mem_rss_peak": 0, "net_rx_bytes": 0, "net_tx_bytes": 0, "start": "string" } ], "resolution": "string", "sandbox_id": "string"}Read the monthly spend budget of the API key's project and its current state. On a workload cell the budget is read from the central control plane and cached briefly, so the response can lag a change made through the management routes by up to the call-through cache TTL (30 seconds by default).
AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Scope: read:spending
The monthly spend budget of the API key's project
application/json- response
A project's monthly spend budget and its current state.
evaluated_at?|When spend was last evaluated in the current period. null until the
first evaluation in the period.
date-timeexceeded_at?|When the project reached its budget this period. null while the
project is under its budget.
date-timemonthly_limit_cents*integerThe monthly budget, in US cents.
int64period_start*stringThe first day of the current budget period (the calendar month in
UTC), as YYYY-MM-DD.
dateproject_id*stringThe project the budget caps.
uuidspent_cents?|Month-to-date spend at list price, in US cents, from the last
evaluation in the current period. null until the first evaluation in
the period.
int64stop_at?|When running sandboxes are ended: exceeded_at plus the grace period.
On the first sweep after this time, running persistent sandboxes are
stopped and running ephemeral sandboxes are deleted; macOS sandboxes,
which run on a prepaid Mac lease, keep running. null when
exceeded_at is null, and null when this time falls on or after
the start of the next UTC month: the hold expires at the month
boundary, so no sandbox is ended this period.
date-timestop_grace_hours*integerThe organization's effective grace period, in hours.
int32curl -X GET 'https://example.com/usage/budget'{ "evaluated_at": "2019-08-24T14:15:22Z", "exceeded_at": "2019-08-24T14:15:22Z", "monthly_limit_cents": 0, "period_start": "2019-08-24", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "spent_cents": 0, "stop_at": "2019-08-24T14:15:22Z", "stop_grace_hours": 0}AuthorizationBearer <token>Project API key (dtn_…) as a Bearer token. Mint via the management API (POST /projects/:id/api-keys) or this deployment's key-mint CLI. Every key carries an explicit set of verb:resource project permissions chosen at mint time (PLAN-API-KEY-PERMISSIONS.md); each operation lists the project permission it requires in its security requirement, and a key lacking it is answered 403 missing required project permission: <project-permission>. Some operations require an additional permission depending on the request body, stated in the operation's description. Holding a mutating verb (write:/delete:/invoke:) implies the resource's read: permission. Operations whose api_key project-permission list is empty need no specific project permission — any live project key works (the global catalogs and the artifact-cache read).
Scope: read:spending
start?stringRFC3339 lower bound (inclusive). Default: end - 1 day.
end?stringRFC3339 upper bound (exclusive). Default: now.
resolution?string"h" (hourly, default) | "d" (daily).
Usage aggregates for the caller's project (available: false when no usage DB is configured)
application/json- response
GET /usage/report body. available: false (usage DB not configured) omits
the interval fields entirely.
available*booleanend?|RFC3339 interval upper bound (exclusive).
items*array<>resolution?|h (hourly) | d (daily).
start?|RFC3339 interval lower bound (inclusive).
curl -X GET 'https://example.com/usage/report'{ "available": true, "end": "string", "items": [ { "interval_start": "string", "resources": { "cpu_core_seconds": 0.1, "disk_bytes_max": 0, "io_r_bytes": 0, "io_w_bytes": 0, "mem_gib_hours": 0.1, "net_rx_bytes": 0, "net_tx_bytes": 0 }, "sandbox_id": "string" } ], "resolution": "string", "start": "string"}