WBX Sandbox
Jobs and batches

Background jobs

Run a command in a fresh sandbox with one call and come back later. The API returns a job_id immediately; the job keeps running without an open connection. When it ends the sandbox is removed, but the log, the result files and an execution receipt are kept for 7 days.

Submit a job

from wbxsandbox import run_job, get_job

job = run_job(command="python analyze.py", template="base", timeout_seconds=3600,
              save_artifacts=True, max_cost="0.10", idempotency_key="report-2026-11")
print(job.id)                                   # returns immediately

job = get_job(job.id).wait()                     # later, from anywhere
print(job.summary()["status"])
job.download("output/report.csv", "report.csv")  # checks the SHA-256
# submit
curl -s -X POST https://sandbox.wbx.cz/v1/jobs -H "Authorization: Bearer YOUR_API_KEY" -H "Idempotency-Key: report-2026-11" \
  -d '{"command": "python analyze.py", "timeout_s": 3600, "artifacts": ["output/"], "max_cost": "0.10"}'

# later: short status, then a result file
curl -s https://sandbox.wbx.cz/v1/jobs/JOB_ID/summary -H "Authorization: Bearer YOUR_API_KEY"
curl -s https://sandbox.wbx.cz/v1/jobs/JOB_ID/artifacts/output/report.csv -H "Authorization: Bearer YOUR_API_KEY" -o report.csv

Request fields – POST /v1/jobs

FieldDescription
commandRequired. Shell command run in a fresh sandbox.
template, timeout_sTemplate (default base) and time limit in seconds (default 3600; max_duration_seconds is an alias).
artifacts, required_artifactsResult files to keep – patterns relative to the working directory, e.g. output/, *.csv – and files that must be saved, otherwise the job fails.
env, networkEnvironment variables and the network, as for sandboxes (including "ip"). Env values are secret – see Secrets.
retry{"max_attempts": 2, "on": "system"} – run again after a failure on our side.
max_costPrice limit in your billing currency (max_cost_eur for EUR accounts) – see Price limit.
idempotency_keyThe same key returns the same job (also as the Idempotency-Key header) – safe to retry the call.
compute_class, optimize_for, placementWhere the job runs – see Compute classes.
dependency_cachefalse turns off the package cache.
inputsResult files of earlier jobs – see Passing files between jobs.
runtime, wasmA WebAssembly job without a virtual machine – see WebAssembly jobs.
webhook_urlA signed notification when the job finishes – see Webhooks.

Returns 202 with the job object.

Endpoints

EndpointWhat it does
GET /v1/jobsYour jobs, newest first: status (one state or several separated by commas, e.g. queued,running), batch_id, since (RFC 3339), limit (max 200) and cursor (from next_cursor). Each row has a shortened command.
GET /v1/jobs/{id}Status, inputs (without env values), timing, error, result files, files that were not saved (artifacts_skipped) and cost.
GET /v1/jobs/{id}/summaryShort status for agents: state, exit code, duration, cost, file names, last log lines, next step.
GET /v1/jobs/{id}/logsThe output log – raw, or a compact digest for AI. See Logs and waiting.
POST /v1/jobs/waitWait on the server until jobs or batches finish – see Waiting for results.
GET /v1/jobs/{id}/receiptThe execution receipt; ?signed=1 signed by WBX – see Execution receipts.
GET /v1/jobs/{id}/artifactsSaved result files (name, size, SHA-256) and files that were skipped.
GET /v1/jobs/{id}/artifacts/{name}Download a result file.
POST /v1/jobs/{id}/cancelStop the job and remove its sandbox.
POST /v1/jobs/{id}/retryNew job with the same inputs. Env values are not stored – send {"env": {…}} again.
GET /v1/jobs/stats?days=30Your cost per completed job, success rate and durations by template and performance class.

States

queued, starting, running, uploading_artifacts, then completed, failed (non-zero exit code, a required file missing, or a platform error after all attempts), cancelled or expired (time limit reached – files written so far are kept). cleanup_pending and recovery_pending mean the platform is still confirming that the previous sandbox is gone; a job never runs in two sandboxes at once.

Cost, refunds and currency

Price limit. With max_cost the worst case (all attempts for the full time limit plus a short start and upload reserve, at your plan's rates) is checked before the job is accepted. If it could exceed the limit, the job is refused and the error tells you the longest time limit that fits. For a limit on all jobs of a month or a day use a budget.

Refunds. Attempts that fail because of a problem on our side (an error with "kind": "system", e.g. sandbox_lost or capacity) are credited back automatically within a few minutes after the job ends. The job shows the credited amount in refund; the credit history in Billing lists it as “Refund – job … failed on our side”. Attempts that fail because of the job itself (non-zero exit, timeout, missing result files) are charged as usual.

Currency. Job costs, price limits, budgets and compute class prices are all in your account's billing currency (CZK, EUR or USD – Billing → Billing details). max_cost and max_total_cost use that currency; the older max_cost_eur and max_total_cost_eur still work for accounts billed in EUR.

Secrets

Env values are stored only encrypted with a per-job key, replaced with [REDACTED] in the log, and made unreadable when the job ends (the key is deleted). They are never part of the execution receipt – only the names of the variables are.

Result files: up to 100 per job, 100 MB each and 512 MB per job, 5 GB stored per team, kept for 7 days – see Limits.