The sandbox's timeline, newest first

What happened in the sandbox, for its org only: lifecycle calls and the statuses the sandbox reached, commands run through exec (command line, exit code and duration), desktop actions, who took control of the desktop, and, when capture_content is enabled, the first and last 4 KiB of command output, typed text, and screenshots with thumbnails. Each event says who caused it. Content capture is off by default.

Environment values, vault values and stdin are never recorded, nor is the output of a command that received stdin: its stdout reads [output not recorded: command received stdin]. Before an event is stored, its command line, output, typed text and errors are masked, best effort: the values of the sandbox’s vault entries (at least 4 bytes, as injected when the sandbox was created and as they are now) and environment variables (at least 8 bytes, the sandbox’s and the command’s own) become [redacted NAME], and common token formats become [redacted]: Authorization, Bearer and Basic header values; sk-, ghp_, gho_, github_pat_, xoxb- and xoxp- tokens; AWS access key IDs; PEM private keys; and the values of token, secret, password and api_key pairs. Other secrets in opted-in content may be recorded. The injected values are held in memory only, so after a restart of the server a vault value replaced since the sandbox was created is no longer masked.

Events are kept for retention.events_days, thumbnails for retention.screenshots_days, and each org’s timeline has a size cap beyond which its oldest events are deleted. Deleting a sandbox deletes its timeline, so a deleted sandbox has none. Page with before set to next_before.

GET/v1/sandboxes/{sandbox}/events

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Path parameters

sandboxstringrequired

Sandbox ID (sbx_...) or name.

Query parameters

beforeinteger<int64>

Return events older than this event ID (next_before of the previous page).

min 1

limitinteger

At most this many events.

min 1 · max 200 · default: 50

typeSandboxEventType[]

Only events of these types; repeat for several.

Responses

200

A page of the timeline.

eventsSandboxEvent[]required

Show properties

Array of SandboxEvent

idinteger<int64>required

Grows with every event.

sandbox_idstringrequired

atstring<date-time>required

typeSandboxEventTyperequired

lifecycle: a lifecycle call or a status the sandbox reached. exec: a command. computer: a desktop action. screenshot: a screenshot of the desktop, present only when content capture is on. control: a person viewing the desktop took control of it, handed it back, or their control lapsed.

Allowed:lifecycleexeccomputerscreenshotcontrol

actorEventActorrequired

Who caused the event.

Show properties

kindstringrequired

api_key: a call with an API key (CLI, MCP, a client); operator: a pols.so operator on the admin pages; system: pols.so itself (the reconciler, the expiry, the monthly sandbox-hours, credit and trial limits, the abuse protection).

Allowed:api_keyoperatorsystem

idstring

The API key's ID.

namestringrequired

The key's name when the event happened, or the system's reason.

summarystringrequired

One line describing the event.

lifecycleLifecycleEventDetail

Show properties

actionstringrequired

create, fork (this sandbox was made as a fork of sandbox), forked (a fork, sandbox, was made from this one), stop, resume, delete and rename (to name) are calls; status means the sandbox reached status.

Allowed:createforkforkedstopresumedeleterenamestatus

statusSandboxStatus

Where the sandbox actually is. pending means not created in the runtime yet, or still booting. running means booted: its guest agent answers, so exec and file calls work. A booting sandbox keeps its previous status, but its running interval (and billing) starts when the VM starts. standby means its VM is frozen with its memory kept because it was idle; the next call that needs it wakes it (see Standby above). error means the reconciler gave up; delete it.

Allowed:pendingrunningstoppeddeletederrorstandby

errorstring

Why the sandbox stopped unexpectedly or failed, as last_error says.

sandboxstring

The other sandbox of a fork.

namestring

The sandbox's new name, on a rename.

execExecEventDetail

Show properties

commandstring[]required

Program and arguments, redacted and cut to 4 KiB in all.

cwdstring

rootboolean

exit_codeinteger

Absent when the command did not finish (see error).

duration_msinteger<int64>required

timed_outboolean

errorstring

Why there is no exit code.

stdoutstring

With content capture on, the first and last 4 KiB of standard output, redacted, without terminal escape sequences; a marker stands for the middle of a longer stream.

stderrstring

The same for standard error.

stdout_bytesinteger<int64>required

The full length of standard output.

stderr_bytesinteger<int64>required

truncatedboolean

The middle of a stream was left out.

streamedboolean

The output was streamed (NDJSON).

computerComputerEventDetail

Show properties

actionComputerActionTyperequired

click: click button at (x, y). double_click: double-click button at (x, y). drag: press the left button at (x, y), move to (to_x, to_y) and release. type: type text as keystrokes. key: press keys. scroll: scroll amount wheel clicks in direction with the pointer at (x, y).

Allowed:clickdouble_clickdragtypekeyscroll

xinteger

yinteger

to_xinteger

to_yinteger

buttonstring

textstring

With content capture on, typed text, redacted and cut to 1 KiB.

keysstring

directionstring

amountinteger

errorstring

Why the action failed.

screenshotScreenshotEventDetail

Show properties

widthintegerrequired

heightintegerrequired

bytesinteger<int64>required

The size of the PNG the call returned.

thumbnailbooleanrequired

A thumbnail is stored (GET .../events/{event}/thumbnail).

controlControlEventDetail

Show properties

actionstringrequired

taken: holder took control of the desktop; released: they handed it back; expired: their control lapsed, for reason.

Allowed:takenreleasedexpired

holderstringrequired

Their name as the desktop's viewers saw it.

reasonstring

Only with expired. idle: they did not use the desktop for 2 minutes; disconnected: they closed it, or the sandbox stopped.

Allowed:idledisconnected

next_beforeinteger<int64>

Pass as before for the next, older page; absent on the last page.

retentionTimelineRetentionrequired

How long the timeline keeps what it records.

Show properties

events_daysintegerrequired

Events are deleted after this many days.

screenshots_daysintegerrequired

Thumbnails are deleted after this many days.

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

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

import requests

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

Response

{
  "events": [
    {
      "id": 0,
      "sandbox_id": "string",
      "at": "2019-08-24T14:15:22Z",
      "type": "lifecycle",
      "actor": {
        "kind": "api_key",
        "id": "string",
        "name": "string"
      },
      "summary": "string",
      "lifecycle": {
        "action": "create",
        "status": "pending",
        "error": "string",
        "sandbox": "string",
        "name": "string"
      },
      "exec": {
        "command": [
          "string"
        ],
        "cwd": "string",
        "root": true,
        "exit_code": 0,
        "duration_ms": 0,
        "timed_out": true,
        "error": "string",
        "stdout": "string",
        "stderr": "string",
        "stdout_bytes": 0,
        "stderr_bytes": 0,
        "truncated": true,
        "streamed": true
      },
      "computer": {
        "action": "click",
        "x": 0,
        "y": 0,
        "to_x": 0,
        "to_y": 0,
        "button": "string",
        "text": "string",
        "keys": "string",
        "direction": "string",
        "amount": 0,
        "error": "string"
      },
      "screenshot": {
        "width": 0,
        "height": 0,
        "bytes": 0,
        "thumbnail": true
      },
      "control": {
        "action": "taken",
        "holder": "string",
        "reason": "idle"
      }
    }
  ],
  "next_before": 0,
  "retention": {
    "events_days": 0,
    "screenshots_days": 0
  }
}

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