# 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

**Python**

```
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
```

**curl**

```
# 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](https://sandbox.wbx.cz/docs/sandboxes/network.md) (including `"ip"`). Env values are secret – see [Secrets](#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](#price). |
| `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](https://sandbox.wbx.cz/docs/jobs/compute.md). |
| `dependency_cache` | `false` turns off the [package cache](https://sandbox.wbx.cz/docs/sandboxes/network.md#depcache). |
| `inputs` | Result files of earlier jobs – see [Passing files between jobs](https://sandbox.wbx.cz/docs/jobs/inputs.md). |
| `runtime`, `wasm` | A WebAssembly job without a virtual machine – see [WebAssembly jobs](https://sandbox.wbx.cz/docs/jobs/wasm.md). |
| `webhook_url` | A signed notification when the job finishes – see [Webhooks](https://sandbox.wbx.cz/docs/jobs/webhooks.md). |

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](https://sandbox.wbx.cz/docs/jobs/logs.md). |
| POST /v1/jobs/wait | Wait on the server until jobs or batches finish – see [Waiting for results](https://sandbox.wbx.cz/docs/jobs/logs.md#wait). |
| GET /v1/jobs/{id}/receipt | The execution receipt; `?signed=1` signed by WBX – see [Execution receipts](https://sandbox.wbx.cz/docs/jobs/receipts.md). |
| 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](https://sandbox.wbx.cz/docs/jobs/budget.md).

**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](https://sandbox.wbx.cz/docs/limits.md).

Source: https://sandbox.wbx.cz/docs/jobs
