Skip to main content
POST
Start an agent run

Headers

x-api-key
string
required

Body

application/json

Create-run request.

api_key
string | null

The API key, on gRPC requests. REST reads the x-api-key header instead.

output_schema
object | null

Optional OpenAI-style response_format object requesting structured output: {"type": "text" | "json_object" | "json_schema", ...}, with name / schema / strict for type json_schema. A structured type adds output.structured and its grounding alongside the cited text. On gRPC the object is JSON-encoded.

query
string
default:""

The natural-language question. Instructions inside the query are followed.

Response

The new run, in pending state.

An agent run.

completed_at
string | null

When the run reached a terminal state. Unset until then.

created_at
string
default:""

When the run was created, as an ISO 8601 timestamp.

id
string
default:""

Unique run id.

object
string
default:""

Object type, always "agent.run".

output
null | object

The run's output. Its members are unset until the run completes.

request
null | object

The request the run was created with.

started_at
string | null

When the run started. Unset while pending.

status
enum<string>
default:pending

Where the run is in its lifecycle.

Available options:
pending,
running,
completed,
failed,
cancelled
stop_reason
null | enum<string>

Why the run stopped. Set once the run reaches a terminal state.

Available options:
finished,
budget_reached,
timeout,
cancelled,
invalid_output,
internal_error