Priced CPU, RAM and disk usage

CPU (busy vCPU time the host measured), RAM (per second while a sandbox runs, or is in standby on the standard engine, at its size’s full RAM) and disk (above the org’s free allowance; on Cloud Hypervisor it includes the memory a sandbox in standby keeps on disk) as priced lines at the list prices of the rate card in effect when the usage happened, which exclude VAT from card 2026-10-05 on (vat_included). Defaults to the current calendar month (UTC) up to now.

GET/v1/usage

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Query parameters

fromstring<date-time>

Start of the window (inclusive, RFC 3339).

tostring<date-time>

End of the window (exclusive, RFC 3339).

Responses

200

The usage report.

fromstring<date-time>required

tostring<date-time>required

rate_cardRateCardrequired

One version of the list prices. From card 2026-10-05 they exclude VAT, which is added when credit is bought; earlier cards' included it. Usage is priced at the card in effect when it happened, so a new card never changes the price of past usage.

Show properties

versionstringrequired

effective_fromstring<date-time> | nullrequired

When the card took effect; null for the first card.

vat_includedbooleanrequired

Whether the prices include VAT; false from card 2026-10-05 on, whose prices exclude it.

busy_vcpu_hour_eurstringrequired

Price of one vCPU fully busy for an hour, as the host measures the sandbox's CPU time (two vCPUs half busy for an hour are one busy vCPU-hour). Decimal string with 6 places.

ram_gib_hour_eurstringrequired

Price of a GiB of the sandbox's size's RAM per hour while it runs or is in standby; nothing while it is stopped. From card 2026-10-04.2, standby on Cloud Hypervisor (an operator opt-in per org) pays no RAM: its memory is on disk and billed as disk. Decimal string with 6 places.

disk_gib_month_eurstringrequired

Price of a GiB-month of used disk (sandboxes in any state and templates, snapshots included) above the org's free allowance. Decimal string with 6 places.

disk_free_gibinteger<int64>required

Disk each org uses free of charge, GiB.

total_secondsinteger<int64>required

Running sandbox-seconds in the window.

total_vcpu_secondsinteger<int64>required

Allocated vCPU-seconds of the running sandboxes; not what is charged.

standby_secondsinteger<int64>required

Sandbox-seconds in standby in the window. They do not count as running time, but on the standard engine the ram lines cover them at the size's full RAM, which the host keeps reserved for a frozen sandbox; on Cloud Hypervisor the memory snapshot of a sandbox in standby is billed as disk instead.

busy_vcpu_secondsinteger<int64>required

Busy vCPU-seconds the host measured, which the cpu lines charge.

estimated_cost_eurstringrequired

The sum of the lines, at list prices (VAT excluded from card 2026-10-05 on). Each hour's usage is taken from the org's credit once the hour is over (see /v1/balance).

linesUsageLine[]required

CPU and RAM lines by sandbox, then disk lines by month.

Show properties

Array of UsageLine

kindstringrequired

Allowed:cpuramdisk

sandbox_idstring

Set on cpu and ram lines.

namestring | null

The sandbox's name, if it has one.

sizeSize

Sandbox size. small: 2 vCPU, 4 GiB RAM, 20 GiB disk. default: 4 vCPU, 8 GiB, 50 GiB. large: 8 vCPU, 16 GiB, 100 GiB. xlarge: 16 vCPU, 32 GiB, 200 GiB. A create that names no size gets small, or the smallest size whose disk holds the template; a sandbox keeps its size for life.

Allowed:smalldefaultlargexlarge

rate_cardstringrequired

Version of the rate card the line is priced at.

fromstring<date-time>required

tostring<date-time>required

quantitystringrequired

In unit; decimal string with 6 places.

unitstringrequired

Allowed:busy vCPU-hourGiB-hourGiB-month

unit_price_eurstringrequired

The card's list price (RateCard.vat_included); decimal string with 6 places.

amount_eurstringrequired

At the card's list price, rounded once from the exact quantity; decimal string with 4 places.

sandboxesSandboxUsage[]required

Show properties

Array of SandboxUsage

sandbox_idstringrequired

namestring | null

sizeSizerequired

Allowed:smalldefaultlargexlarge

secondsinteger<int64>required

Seconds the sandbox ran in the window.

standby_secondsinteger<int64>required

Seconds the sandbox was in standby in the window: not running time, but its ram line covers them, at its size's full RAM, on the standard engine; on Cloud Hypervisor its memory snapshot is billed as disk instead.

busy_vcpu_secondsinteger<int64>required

Busy vCPU-seconds the host measured, whole hours that start in the window.

estimated_cost_eurstringrequired

Its cpu and ram lines; disk is charged per org.

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

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/usage' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch("https://api.pols.so/v1/usage", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "https://api.pols.so/v1/usage",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "from": "2019-08-24T14:15:22Z",
  "to": "2019-08-24T14:15:22Z",
  "rate_card": {
    "version": "string",
    "effective_from": "2019-08-24T14:15:22Z",
    "vat_included": true,
    "busy_vcpu_hour_eur": "string",
    "ram_gib_hour_eur": "string",
    "disk_gib_month_eur": "string",
    "disk_free_gib": 0
  },
  "total_seconds": 0,
  "total_vcpu_seconds": 0,
  "standby_seconds": 0,
  "busy_vcpu_seconds": 0,
  "estimated_cost_eur": "string",
  "lines": [
    {
      "kind": "cpu",
      "sandbox_id": "string",
      "name": "string",
      "size": "small",
      "rate_card": "string",
      "from": "2019-08-24T14:15:22Z",
      "to": "2019-08-24T14:15:22Z",
      "quantity": "string",
      "unit": "busy vCPU-hour",
      "unit_price_eur": "string",
      "amount_eur": "string"
    }
  ],
  "sandboxes": [
    {
      "sandbox_id": "string",
      "name": "string",
      "size": "small",
      "seconds": 0,
      "standby_seconds": 0,
      "busy_vcpu_seconds": 0,
      "estimated_cost_eur": "string"
    }
  ]
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}