# Runs and sessions A cloud run executes one Workbench version in a Daytona sandbox, or on one of your organization's workers, and records everything it does as events. A session is the thread: one Workbench at a pinned version, one workspace, and the runner's native context. A run is one bounded execution in a session. Runs belong to the organization that starts them, never to the Workbench's publisher. A run that does not exist is a 404; one that exists answers 403 to a caller outside its organization, and to a key of its organization without the scope. ## The run object | Field | Type | Meaning | | -------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `wb_...` | | | `session_id` | `wbs_...` | | | `organization_id` | UUID | | | `workbench_id`, `version_id` | UUID | | | `workbench` | object | `id`, `slug`, `organization_slug`. | | `version` | object | `id`, `version`, `digest`. | | `package_digest` | string | SHA-256 of the package that runs. | | `project` | object or null | `slug`, `name`. | | `kind` | `initial` or `continuation` | | | `status` | string | `queued`, `provisioning`, `starting`, `running`, `needs_input`, `completing`, `completed`, `failed`, or `cancelled`. | | `task` | string | | | `executor` | string | Where it runs, such as `worker` for a worker run. | | `worker` | object or null | `id`, `slug`, and `runtime` (`docker` or `local`) for a worker run. | | `final_response` | string or null | The last assistant response. | | `terminal_reason` | string or null | Why the run failed or was refused. | | `usage` | object or null | `input_tokens`, `output_tokens`, `cost_usd` (or null). | | `outcome_size` | integer or null | Bytes of the kept outcome. | | `branch` | string | For a repository run: the branch the agent may push, such as `workbenches/fix-login`. | | `delivery` | object | Present when the agent opened or updated a pull request: `state` (`published`), `branch`, `base_branch`, `commit`, `pull_request` (`number`, `url`). | | `idempotency_key` | string | | | `max_minutes` | integer | The stored time limit. | | `previews` | list | Announced previews: `name`, `port`. | | `previews_until` | date-time or null | When an open preview window closes. | | `created_at`, `started_at`, `completed_at`, `updated_at` | date-time | `started_at` and `completed_at` may be null. | Status is derived from events. `needs_input` means a permission or question is pending. ## Start a run `POST /v1/runs` Key `runs:write`, or session: member. | Field | Type | Meaning | | ----------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `workbench` | `"org/name"` or `{ "version_id": "uuid" }` | Required. `org/name` resolves to the latest version. Internal Workbenches resolve only for their own organization. | | `task` | string, 1 to 100,000 characters | Required. | | `idempotency_key` | string, 1 to 200 characters | Required. A repeated key returns the original run with 200. | | `organization` | slug | For a session: the organization to run in. A key always runs in its own. | | `project` | string | An existing project name or slug. A run never creates a project. | | `workspace` | object | `repository` (`owner/name`), `ref` (cannot start with `-`), and optional `branch`. See [Repositories and pull requests](/docs/cloud/repositories). | | `max_minutes` | integer, 1 to 1440 | The time limit. Default 60. | | `worker` | slug | Run on this worker instead of a cloud sandbox. | | `connection` | string | The model provider connection to use, such as `openrouter`. A sandbox run takes only `openrouter`; other providers need a worker. | | `session_id` | `wbs_...` | Not supported in the cloud yet: a run with it fails with that reason, and it cannot be combined with `workspace`. | ```sh curl https://api.workbenches.dev/v1/runs \ -H "Authorization: Bearer $WORKBENCHES_KEY" \ -H "Content-Type: application/json" \ -d '{ "workbench": "acme/code-review", "task": "Review the open migration and open a draft pull request with fixes.", "workspace": { "repository": "acme/api", "ref": "main", "branch": "migration-review" }, "max_minutes": 90, "idempotency_key": "migration-review-1" }' ``` Response `201` (or `200` for a repeated key): the run. ### Errors | Status | When | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 `validation_failed` | A field breaks its rule, such as `max_minutes` over 1440 or an invalid branch name. The message says which. | | 402 `plan_limit` | No payment method, no sandbox time left, the spend limit reached, or `max_minutes` longer than the time available. | | 403 | The worker is personal to another member: `The worker is personal to .` | | 404 | No such Workbench, version, project, or worker, or you cannot see it. | | 409 | The version is not sandboxed and is not placed on a worker's `local` runtime: `This Workbench runs locally only. Install it with wb add and run it with the wb CLI.` | | 409 `branch_in_use` | Another unfinished run of the organization uses this branch of this repository. | | 409 `worker_offline` | The worker is not connected. | | 422 `worker_unsuitable` | The worker offers no declared runtime, does not meet the requirements, or the package is over 64 MiB. | | 422 | A sandbox run names a `connection` other than `openrouter`: `A cloud run uses the organization's OpenRouter key. Run it on a worker where you are signed in to use .` | A run that is accepted but breaks a cloud rule (no OpenRouter route, a missing secret, an unfetchable repository) fails with the reason in `terminal_reason`, before any sandbox exists. ## List runs `GET /v1/runs` Key `runs:read`, or session: member. Newest first. | Query | Type | Meaning | | -------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organization` | slug | For a session. | | `session` | `wbs_...` | Only this session's runs. | | `project` | string | Only this project's runs. | | `status` | run status | Exact status, intersected with `view` when both are provided. | | `view` | `all`, `active`, `needs_input`, or `finished` | Status group applied before pagination. Active includes queued, provisioning, starting, running, and completing; finished includes completed, failed, and cancelled. | | `worker` | UUID | Only runs on this worker. | | `cursor` | string | `next` from the previous page. | | `limit` | integer, 1 to 100 | Default 25. | Response `200` `{ "runs": [ ... ], "next": "cursor or null" }`. ## Get a run `GET /v1/runs/:id` Key `runs:read`, or session: member. Response `200`: the run. ## Sessions ### The session object | Field | Type | Meaning | | ---------------------------- | -------------------- | ------------------------------------------------------------------------ | | `id` | `wbs_...` | | | `organization_id` | UUID | | | `key_id` | UUID or null | The key that started it. | | `created_by` | UUID or null | The user that started it. | | `workbench_id`, `version_id` | UUID | | | `project` | object or null | `slug`, `name`. | | `package_digest` | string | | | `runner`, `model`, `runtime` | string | | | `workspace` | object | `{ "kind": "repository", "repository", "ref" }` or `{ "kind": "none" }`. | | `status` | `active` or `closed` | | | `latest_run_id` | `wb_...` or null | | | `created_at`, `updated_at` | date-time | | ### List sessions `GET /v1/sessions` Key `runs:read`, or session: member. Newest first. | Query | Type | Meaning | | -------------- | ----------------- | -------------- | | `organization` | slug | For a session. | | `project` | string | | | `cursor` | string | | | `limit` | integer, 1 to 100 | Default 25. | Response `200` `{ "sessions": [ ... ], "next": "cursor or null" }`. ### Get a session `GET /v1/sessions/:id` Key `runs:read`, or session: member. Response `200`: the session. ## Related - [Events](/docs/api/events): the run's event stream. - [Commands](/docs/api/commands): send, steer, queue, answer, cancel. - [Outcomes and changes](/docs/api/outcomes): what the run returned. - [Live previews](/docs/cloud/previews#api): preview links.