Metrics

Live resource usage for a single sandbox, plus account-wide usage aggregates for dashboards and billing visibility.

Get your API key from https://createos.nodeops.network/profile. Pass it as X-Api-Key: <token> on every request below.

Base URL: https://api.sb.createos.sh

At a glance

• Base URL: https://api.sb.createos.sh
• Auth: X-Api-Key: <token> header. Get a token
• Response envelope: JSend, {"status": "...", "data": ...}

There are two scopes. GET /v1/sandboxes/{id}/metrics is per-sandbox and owner-gated, returning a live CPU/memory snapshot. GET /v1/metrics and GET /v1/metrics/timeseries are account-wide, aggregating usage across all of the caller's sandboxes over a time window. All figures are observational and carry no atomicity guarantee against concurrent activity.

GET /v1/sandboxes/{id}/metrics

Read the owning host's cgroup files on demand and return live memory and CPU figures for one sandbox. Owner-gated: you can only read metrics for sandboxes you own.

Auth required: Yes

Example

Bash
Copy
1curl https://api.sb.createos.sh/v1/sandboxes/sb-01K.../metrics \
2  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "sandbox_id": "sb-01K...",
5    "memory_bytes": 134217728,
6    "memory_limit_bytes": 1073741824,
7    "memory_pct": 12.5,
8    "cpu_cores_used": 0.42,
9    "cpu_cores_allocated": 1.0,
10    "cpu_pct": 42.0,
11    "as_of": "2026-06-28T12:34:56Z"
12  }
13}

Response fields

Notable errors: 404 sandbox not found or not owned by the caller.

GET /v1/metrics

Account-wide usage. Returns a live status snapshot (current) plus aggregates over a time window (window) in one envelope, so a dashboard can fetch both in a single call.

Auth required: Yes

Query parameters

The window span is capped at 30 days. An inverted window (from after to) returns 400.

Example

Bash
Copy
1curl "https://api.sb.createos.sh/v1/metrics?from=2026-06-27T12:00:00Z&to=2026-06-28T12:00:00Z" \
2  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "current": { "running": 3, "paused": 1 },
5    "window": {
6      "from": "2026-06-27T12:00:00Z",
7      "to": "2026-06-28T12:00:00Z",
8      "spawned": 18,
9      "destroyed": 15,
10      "lifetime_seconds": { "min": 4.2, "p50": 310.5, "p95": 1820.0, "average": 540.7 },
11      "compute": { "vcpu_seconds": 9720.0, "mem_mib_seconds": 9953280.0, "disk_mib_seconds": 99532800.0 },
12      "bandwidth_bytes": { "egress": 524288000, "ingress": 104857600 },
13      "by_shape": [
14        { "shape": "s-1vcpu-1gb",   "count": 12, "vcpu_seconds": 6480.0 },
15        { "shape": "s-1vcpu-256mb", "count": 6,  "vcpu_seconds": 3240.0 }
16      ]
17    }
18  }
19}

Top-level fields

window fields

Notable errors: 400 invalid or inverted window, 401 invalid API key.

GET /v1/metrics/timeseries

Account-wide bucketed counts for charts. Returns one row per time bucket across the window.

Auth required: Yes

Query parameters

The window span is capped at 30 days. An inverted window returns 400.

Example

Bash
Copy
1curl "https://api.sb.createos.sh/v1/metrics/timeseries?bucket=day&from=2026-06-21T12:00:00Z&to=2026-06-28T12:00:00Z" \
2  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "from": "2026-06-21T12:00:00Z",
5    "to": "2026-06-28T12:00:00Z",
6    "bucket": "day",
7    "buckets": [
8      { "ts": "2026-06-21T00:00:00Z", "spawned": 5, "destroyed": 4, "running": 2 },
9      { "ts": "2026-06-22T00:00:00Z", "spawned": 8, "destroyed": 7, "running": 3 }
10    ]
11  }
12}

Response fields

Notable errors: 400 invalid bucket or inverted window, 401 invalid API key.