Events & results

Stream a Run

curl -N \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions/$SESSION_ID/runs/$RUN_ID/events" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "last-event-id: 42"

id: 42
event: run.output
data: {"id":42,"type":"run.output"}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Run events use Server-Sent Events. Each durable event has an ID; store the last processed ID together with your application’s processing progress. Native payloads remain harness-specific. Use normalized Run state for application status, and preserve native payloads when inspecting detailed execution.

Reconnect without repeating work

Send Last-Event-ID or after with the last received ID to replay later events. The tutorial’s generated example shows the replay header; omit it for a first connection. Heartbeats keep an idle observer active, but proxies and networks can still disconnect.

Closing the stream does not stop the Run. Keep the existing Run ID and reconnect. Use the Run detail API to reconcile state independently of the stream connection.

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions/$SESSION_ID/runs/$RUN_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "id": "",
    "environmentId": "",
    "sessionId": "",
    "environmentSequence": -9007199254740991,
    "model": "",
    "input": "",
    "files": [
      {
        "path": ""
      }
    ],
    "status": "queued",
    "stopRequested": false,
    "fileDiff": [
      {
        "path": "",
        "kind": "added"
      }
    ],
    "fileDiffStatus": "pending",
    "checkpoint": {
      "status": "pending"
    },
    "createdAt": "2026-10-12T01:00:00Z",
    "usage": {
      "calls": [],
      "serviceFeePercent": 0,
      "upstreamAmountUsd": "",
      "serviceFeeUsd": "",
      "totalAmountUsd": "",
      "sandboxAmountUsd": ""
    }
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Separate completion from checkpoint readiness

A terminal execution event means the native task ended. Output can be available while the file diff, checkpoint or accounting is still settling. checkpoint.status and fileDiffStatus are separate from Run status. Watch checkpoint events or poll the Run before accessing files or forking.

Transient Sandbox0 conflicts, rate limits and service errors can leave checkpoints pending with diagnostic text. The worker retries with backoff; checkpoint recovery does not execute the model task again.

Inspect changed files

The Run diff lists added, modified and deleted regular files under /workspace with before/after SHA-256 identities. Sandpi-managed state, Git metadata and generated caches are excluded. Diff computation can fail on a large workspace while Run output and the checkpoint remain valid.

Retrieve actual file content through the file API; the diff is a manifest, not a patch download.

Interpret usage evidence

Run usage reports posted Sandbox runtime charges. The model-call and service-fee fields are retained for historical managed-model settlement; new BYOK Runs do not populate that ledger. Model token usage and cost must come from native Harness events where available and your provider or gateway records. See billing for attribution and settlement timing. Record commands, exit codes and validation results in a workspace artifact when your Controller requires a reproducible execution report.

Account for retention

Content retention can clear output and replayable content events while leaving minimal Run identity and settlement facts. Check contentDeletedAt when historical content is missing. See retention and deletion and billing.

Runtime availability

When Sandbox execution or observation times out, the Run exposes error.code = platform_runtime_unavailable and emits run.runtime_unavailable. The console displays this diagnostic even while the Run remains running: the native task may still be executing. High CPU or memory load is one possible cause; a timeout alone does not establish OOM.

Keep the same Run ID. Reconciliation retries with backoff and reconnects to the original execution. Successful runtime access clears the transient error and emits run.runtime_recovered. These events do not stop, restart or duplicate the task. Use the Environment's Settings to check Sandbox health and resource usage; release unused browser tabs or processes before retrying access.

Runtime warnings appear before any optional resource query. A background telemetry-only query has a shared two-second deadline and is limited to once per Environment every 30 seconds. If supported, run.resource_observation adds timestamped CPU and memory samples to the existing warning. The same observations appear after a TUI connection error. Normal connections issue no additional diagnostic requests.

Only fresh, continuous samples from the current runtime are shown. A single spike, missing bucket, collector reset, stale/partial response, changed generation or mismatched memory limit does not establish sustained load. “Near its allocated limit” requires every sample in a sequence spanning at least 15 seconds to be at least 95%. This describes quota utilization, not an abnormal task, an OOM event, or proof that resource use caused the timeout. Missing or slow telemetry leaves the cause unconfirmed.