Skip to main content
POST
Start a run

Authorizations

Authorization
string
header
required

Your API key. Tool calls under tools_url use the run token instead.

Body

application/json
environment
string
required

An environment id or slug.

task
string
required

A task id, the title of one of the environment's tasks, or free text. A template task brings its checks. Free text has none.

Maximum string length: 8192
checks
object[]

Your own checks, in addition to the template's.

replace_template_checks
boolean

true drops the task's template checks.

agent
object
max_calls
integer
default:500
Required range: 1 <= x <= 500
idle_timeout_seconds
integer
default:600
Required range: 30 <= x <= 3600
timeout_seconds
integer
default:3600
Required range: 60 <= x <= 86400
idempotency_key
string

The same key with the same body replays the first run. With a different body it is 409 idempotency_conflict.

Required string length: 1 - 255
metadata
object

Free-form, at most 4 KB. Returned unchanged.

Response

The run, in status created, with its token.

One agent doing one task in one environment.

id
string

Opaque id, starts with run_.

status
enum<string>
Available options:
created,
running,
evaluating,
done,
failed
ended_by
enum<string> | null
Available options:
finish,
idle_timeout,
timeout,
max_calls,
null
error
object | null
environment
object
task
object
agent
object
tools_url
string

The agent's base address for the tools.

mcp_url
string

One MCP address for the Gmail and Slack tools.

tools
object[]
token
string

The run's credential for the tools, tw_run_... Only in the answers of POST /v1/runs and GET /v1/runs/{id}/tools.

now
string<date-time>

Simulated time after the last call.

calls
integer
max_calls
integer
idle_timeout_seconds
integer
timeout_seconds
integer
created_at
string<date-time>
started_at
string<date-time> | null
expires_at
string<date-time>
finished_at
string<date-time> | null
scored_at
string<date-time> | null
metadata
object
trace
object | null

Every call the tools answered during the run, reads included. Nothing from inside the agent.

evaluation
object | null

The end state and the output compared with the run's checks.