Run the agent

Execute a web research task. Supports both streaming (SSE) and non-streaming responses. This is the single consolidated endpoint that replaces /query, /extract, and /plan.

Request body

promptstring required

The research task or question.

streamboolean

If true, response is an SSE stream of AgentEvent objects.

format'json' | 'markdown'

Desired output format. If set, agent will format data accordingly.

schemaobject

JSON schema that serves as both a research plan and output format. The agent treats each field as a data point to collect during research. Array fields mean "find all items." The final output is compiled into this exact shape. Used with format=json.

columnsstring[]

Column names for CSV output. Each column acts as a required data point the agent will research. The final CSV contains one column per entry.

urlsstring[]

Seed URLs to start from instead of searching.

maxStepsinteger

Maximum agent steps before stopping.

skillsstring[]

Skills to pre-load for this run.

skillInstructionsobject

Per-skill custom instructions. Keys are skill names, values are instruction strings appended when the skill is loaded.

exportSkillboolean

When true, post-processes the run into a reusable skill package (SKILL.md + workflow.mjs + schema.json) returned in the response.

Example request

{
  "prompt": "Get pricing for Vercel, Netlify, and Cloudflare Pages"
}

Response

Successful response

textstring

The agent's final text response.

datastring

Formatted output (present when format was specified).

format'json' | 'markdown' | 'text'

The format of the data field.

durationMsinteger

Wall-clock duration of the run in milliseconds.

modelstring

Model that produced this response, as "provider:id".

Example response

{
  "model": "google:gemini-3-flash-preview"
}

v1

Run the agent

Request body

Example request

Response

Example response