Skip to main content
POST

Authorizations

Authorization
string
header
required

API key ret_live_… created in Settings → API keys.

Headers

Idempotency-Key
string

Unique client-side request id (e.g. UUID). Must not be empty.

Minimum string length: 1

Body

application/json
prompt
string
required

Natural-language instruction. Must not be empty. The agent does not ask clarifying questions: put every decision here. A later run on the same conversation_id corrects a choice.

Minimum string length: 1
workspace_id
string

Existing workspace. Without conversation_id, the run opens a new conversation there; with it, it must be the conversation's workspace. Without both, a workspace is created.

conversation_id
string

Continues this conversation: the agent keeps its history and tables. Use it to refine or extend an earlier result.

output
object

Optional output contract. Without it, the run returns message, artifacts, and output: null.

Response

Run accepted.

id
string
workspace_id
string
conversation_id
string
status
enum<string>
Available options:
queued,
running,
recovering,
completed,
failed,
cancelled
message
string | null

Agent's final text.

artifacts
object[]

Tables created or updated by the run (live state).

last_heartbeat_at
string<date-time> | null
progress
object
output
object | null
error
object | null
credits
object

Only on GET /v1/runs/{id}. The list, create and cancel responses do not include it. It is also missing when your credit history could not be read: read the run again.

created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null

Null while the run is queued. The maximum run duration counts from here.

completed_at
string<date-time> | null
cancellation_requested
boolean
queue
object | null

Set on every queued run read with GET /v1/runs/{id}, null once the run has left the queue. On the 202 of POST /v1/runs, queue can be null or already out of date: GET /v1/runs/{id} is the reference.