Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview

A sandbox's current CPU, memory and disk use and its recent history

The control plane samples every running sandbox at a fixed interval (interval_seconds) and keeps the samples of the last hour in memory; they start over when the control plane restarts. current is present while the sandbox runs and has a recent sample. A stopped sandbox keeps the history of its last run until it ages out. Answers 503 when the deployment does not sample resources.

GET/v1/sandboxes/{sandbox}/stats
Authorization
AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Path parameters
sandboxstringrequired

Sandbox ID (sbx_...) or name.

Responses
200

The sandbox's resource use.

sandbox_idstringrequired
interval_secondsintegerrequired

How often running sandboxes are sampled.

currentResourceStats

One sample of a running sandbox's resource use, as stats on a sandbox (present while it runs and has a recent sample) and in GET /v1/sandboxes/{sandbox}/stats.

Show properties
sampled_atstring<date-time>required
cpu_percentnumber<double>

Share of the sandbox's vCPUs that were busy, averaged since the previous sample: 100 means all of them. Absent in the first sample after the sandbox starts.

cpu_coresnumber<double>

The same as a number of busy vCPUs, for example 1.5. Absent with cpu_percent.

memory_used_bytesinteger<int64>required

Memory in use inside the VM, as its guest agent reports it.

memory_total_bytesinteger<int64>required

Memory the guest sees (slightly less than the size's RAM, which the guest kernel reserves part of).

disk_used_bytesinteger<int64>required

Space the root disk volume takes in the host's storage pool, as the pool reports it. On a copy-on-write clone (a sandbox created from a template, or a fork) this can leave out blocks it still shares with its origin. 0 when the host does not report it.

disk_total_bytesinteger<int64>required

Size of the root disk.

historyResourceStats[]required

The samples of the last hour, oldest first, including current.

Show properties
Array of ResourceStats
sampled_atstring<date-time>required
cpu_percentnumber<double>

Share of the sandbox's vCPUs that were busy, averaged since the previous sample: 100 means all of them. Absent in the first sample after the sandbox starts.

cpu_coresnumber<double>

The same as a number of busy vCPUs, for example 1.5. Absent with cpu_percent.

memory_used_bytesinteger<int64>required

Memory in use inside the VM, as its guest agent reports it.

memory_total_bytesinteger<int64>required

Memory the guest sees (slightly less than the size's RAM, which the guest kernel reserves part of).

disk_used_bytesinteger<int64>required

Space the root disk volume takes in the host's storage pool, as the pool reports it. On a copy-on-write clone (a sandbox created from a template, or a fork) this can leave out blocks it still shares with its origin. 0 when the host does not report it.

disk_total_bytesinteger<int64>required

Size of the root disk.

429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), forbidden (403), quota_exceeded (403), not_found (404), conflict (409), rate_limited (429, see Retry-After), internal (500), runtime_error (502, the sandbox host failed), unavailable (503, the feature is not configured on this deployment), timeout (504, or 408 when a request body stalls).

messagestringrequired
default

Error.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), forbidden (403), quota_exceeded (403), not_found (404), conflict (409), rate_limited (429, see Retry-After), internal (500), runtime_error (502, the sandbox host failed), unavailable (503, the feature is not configured on this deployment), timeout (504, or 408 when a request body stalls).

messagestringrequired
Request
curl -X GET 'https://api.pols.so/v1/sandboxes/string/stats' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "sandbox_id": "string",
  "interval_seconds": 0,
  "current": {
    "sampled_at": "2019-08-24T14:15:22Z",
    "cpu_percent": 0.1,
    "cpu_cores": 0.1,
    "memory_used_bytes": 0,
    "memory_total_bytes": 0,
    "disk_used_bytes": 0,
    "disk_total_bytes": 0
  },
  "history": [
    {
      "sampled_at": "2019-08-24T14:15:22Z",
      "cpu_percent": 0.1,
      "cpu_cores": 0.1,
      "memory_used_bytes": 0,
      "memory_total_bytes": 0,
      "disk_used_bytes": 0,
      "disk_total_bytes": 0
    }
  ]
}