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
| Field | Description |
|---|---|
command | Required. Shell command run in a fresh sandbox. |
template, timeout_s | Template (default base) and time limit in seconds (default 3600; max_duration_seconds is an alias). |
artifacts, required_artifacts | Result files to keep – patterns relative to the working directory, e.g. output/, *.csv – and files that must be saved, otherwise the job fails. |
env, network | Environment 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_cost | Price limit in your billing currency (max_cost_eur for EUR accounts) – see Price limit. |
idempotency_key | The same key returns the same job (also as the Idempotency-Key header) – safe to retry the call. |
compute_class, optimize_for, placement | Where the job runs – see Compute classes. |
dependency_cache | false turns off the package cache. |
inputs | Result files of earlier jobs – see Passing files between jobs. |
runtime, wasm | A WebAssembly job without a virtual machine – see WebAssembly jobs. |
webhook_url | A signed notification when the job finishes – see Webhooks. |
Returns 202 with the job object.
Endpoints
| Endpoint | What it does |
|---|---|
| GET /v1/jobs | Your 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}/summary | Short status for agents: state, exit code, duration, cost, file names, last log lines, next step. |
| GET /v1/jobs/{id}/logs | The output log – raw, or a compact digest for AI. See Logs and waiting. |
| POST /v1/jobs/wait | Wait on the server until jobs or batches finish – see Waiting for results. |
| GET /v1/jobs/{id}/receipt | The execution receipt; ?signed=1 signed by WBX – see Execution receipts. |
| GET /v1/jobs/{id}/artifacts | Saved 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}/cancel | Stop the job and remove its sandbox. |
| POST /v1/jobs/{id}/retry | New job with the same inputs. Env values are not stored – send {"env": {…}} again. |
| GET /v1/jobs/stats?days=30 | Your 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.