The org's credit balance and the credit it was granted

Billing (billing_enabled) is on for a new org from the start of its trial, at signup or once its signup is approved; an existing org has it off until an operator switches it on (polsd admin set-billing). While it is off, usage is metered and shown but not charged, nothing is refused or stopped for lack of credit, and the org’s monthly sandbox-hours quota (monthly_sandbox_hours on /v1/org) caps its usage instead. Once it is on, the org pays its usage from credit: each hour’s priced usage (/v1/usage) is taken from its credit once the hour is over, from the credit that expires first, prepaid credit last. available_eur is that credit, less any debt and the usage not yet taken from it, so it falls while sandboxes run. At zero, running sandboxes are stopped (their disks are kept) and none can start (402 insufficient_credit) until it is positive again; disk above the free allowance keeps costing, and what the credit cannot pay becomes debt, taken first from the next credit.

GET/v1/balance

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Responses

200

The balance.

billing_enabledbooleanrequired

Whether billing is switched on for the org. Only then is usage taken from the credit, are starts refused without credit, are running sandboxes stopped at zero and do the trial limits apply; until then the monthly sandbox-hours quota applies instead.

trialbooleanrequired

The org has never been granted subscription or prepaid credit. While billing is on, a trial org runs one small or default sandbox at a time with 20 GiB of disk, and all trial orgs together reserve at most 8 GiB of host memory, overcommitted like the hosts' (12 GiB at the default --memory-overcommit of 1.5; trial_credit.limits.total_memory_gib is the configured value).

available_eurstringrequired

credit_eur less debt_eur and unsettled_eur, except that credit that expired since settled_to still pays for the unsettled usage of the hours before it expired; VAT included, decimal string with 4 places, negative when in debt. While billing is on, the org's sandboxes can start only while it is positive.

credit_eurstringrequired

What the lots that have not expired hold. While billing is off no lot expires; a lot whose expiry date has passed is forfeited when billing is switched back on, unless it is an untouched trial, which restarts.

debt_eurstringrequired

Usage no credit could pay for, taken first from the next credit.

unsettled_eurstringrequired

Usage since settled_to, not yet taken from the credit; 0 while billing is off.

settled_tostring<date-time> | nullrequired

The hour up to which usage was taken from the credit; null while billing is off.

lotsCreditLot[]required

Every lot the org was granted, oldest first.

Show properties

Array of CreditLot

idstringrequired

kindstringrequired

Allowed:trialsubscriptionprepaid

amount_eurstringrequired

Granted, VAT included; decimal string with 4 places.

remaining_eurstringrequired

What is left of it; 0 once it expired.

granted_atstring<date-time>required

expires_atstring<date-time> | nullrequired

When what is left of it is forfeited, if billing is on by then; null for never.

trial_creditTrialCredit | nullrequired

The org's trial credit and what became of it; null if it was never granted one.

Show properties

Any of:

TrialCredit

stateTrialStaterequired

not_started: billing is off for the org and nothing was taken from the trial credit; the trial starts once billing is switched on. active: usage is taken from it. used_up: usage took all of it. expired: what was left of it was forfeited.

Allowed:not_startedactiveused_upexpired

lot_idstringrequired

amount_eurstringrequired

Granted, VAT included; decimal string with 4 places.

used_eurstringrequired

What usage took from it, the usage not yet taken from the credit (unsettled_eur) included.

remaining_eurstringrequired

What is left to use; 0 once it is used up or expired.

forfeited_eurstringrequired

What was left of it when it expired; 0 otherwise.

granted_atstring<date-time>required

expires_atstring<date-time> | nullrequired

When what is left of it is forfeited; null while the trial has not started, or if it never expires.

days_leftinteger | nullrequired

Days until it expires, rounded up; null unless the trial is active, expires and billing is on.

limitsTrialLimits | nullrequired

The trial limits, which apply to the org while billing is on; null once it was granted subscription or prepaid credit, which ends them.

Show properties

Any of:

TrialLimits

max_runningintegerrequired

Sandboxes the org may run at a time.

sizesSize[]required

The sizes its sandboxes may have.

disk_gibinteger<int64>required

The disk the org may hold; its running sandboxes stop above it.

total_memory_gibintegerrequired

The RAM all trial orgs' sandboxes together may reserve at once (429 trial_capacity beyond it), as configured: 8 GiB of host memory, overcommitted like the hosts' (12 GiB at the default --memory-overcommit of 1.5).

null

null

null

null

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

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

import requests

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

Response

{
  "billing_enabled": true,
  "trial": true,
  "available_eur": "string",
  "credit_eur": "string",
  "debt_eur": "string",
  "unsettled_eur": "string",
  "settled_to": "2019-08-24T14:15:22Z",
  "lots": [
    {
      "id": "crd_3k9x2m1q8zt4",
      "kind": "trial",
      "amount_eur": "string",
      "remaining_eur": "string",
      "granted_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  ],
  "trial_credit": {
    "state": "not_started",
    "lot_id": "crd_3k9x2m1q8zt4",
    "amount_eur": "string",
    "used_eur": "string",
    "remaining_eur": "string",
    "forfeited_eur": "string",
    "granted_at": "2019-08-24T14:15:22Z",
    "expires_at": "2019-08-24T14:15:22Z",
    "days_left": 0,
    "limits": {
      "max_running": 1,
      "sizes": [
        "small"
      ],
      "disk_gib": 20,
      "total_memory_gib": 12
    }
  }
}

{
  "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"
    }
  }
}