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), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired
Show properties
codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), withdrawal_consent_required (409, a consumer orders a top-up or the subscription only with withdrawal_consent), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired
controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties
heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

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
    }
  ]
}