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.sh/app/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

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

Success response 200

{
  "status": "success",
  "data": {
    "sandbox_id": "sb-01K...",
    "memory_bytes": 134217728,
    "memory_limit_bytes": 1073741824,
    "memory_pct": 12.5,
    "cpu_cores_used": 0.42,
    "cpu_cores_allocated": 1.0,
    "cpu_pct": 42.0,
    "as_of": "2026-06-28T12:34:56Z"
  }
}

Response fields

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

GET /v1/sandboxes/{id}/metrics/timeseries

Read recent resource samples for a sandbox you own. Authenticate with X-Api-Key. This per-sandbox endpoint returns a rolling one-hour window with 10-second sampling, rather than the account-wide daily/hourly aggregates below.

curl "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/metrics/timeseries" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

The JSend data object contains sandbox_id, step_seconds (10), window_seconds (3600), and points in chronological order. Each point contains:

A new sandbox may have no samples yet. A zero reading can indicate an unavailable measurement. Treat this as recent operational history, not a durable billing record. The endpoint returns 404 for a sandbox you cannot access; history availability depends on the sandbox's host.

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

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

Success response 200

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

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

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

Success response 200

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

Response fields

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