Workbenches is an open standard. Read why
Docs Runs and sessions

API reference

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.
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. 
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 <name> is personal to <owner name>.
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 <ref> 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 <connection>.

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.