Skip to main content
POST
Start a task

Authorizations

Authorization
string
header
required

An org API key (gh_live_…) from Settings → API keys in the console.

Path Parameters

session_id
string
required

The session’s code.

Body

application/json
prompt
string
required

What should happen on their computer, in plain language.

Maximum string length: 8000
Example:

"Turn on Dark Mode"

agent_id
string

Run a different agent than the session’s.

request_id
string

Idempotency key: the same request_id returns the same task instead of starting another.

metadata
object

Your own ids and labels (e.g. a ticket or customer id), returned as given.

Example:

Response

OK

object
any
task_id
string
session_id
string
agent_id
string
status
enum<string>
Available options:
queued,
running,
waiting_for_user,
waiting_for_approval,
completed,
failed,
stopped
done
boolean
prompt
string
result
string | null

The agent’s summary when it finished.

error
string | null
pending
Question · object

What the agent waits on: answer it with /respond.

cursor
integer

The latest event’s cursor.

metadata
object

Your own ids and labels (e.g. a ticket or customer id), returned as given.

Example:
created_at
string<date-time>
updated_at
string<date-time>
active_seconds
integer

Time spent running (not waiting on a person).

billed_minutes
integer | null
replay_url
string

The replay in the console.

recording
object
events
object[]

With include=events.