---
title: "Run the agent"
method: POST
path: "/run"
---

# Run the agent

`POST /run`

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

- RunRequest
  - `prompt` string, required — The research task or question.
  - `stream` boolean — If true, response is an SSE stream of AgentEvent objects.
  - `format` 'json' | 'markdown' — Desired output format. If set, agent will format data accordingly.
  - `schema` object — 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.
  - `columns` string[] — 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.
  - `urls` string[] — Seed URLs to start from instead of searching.
  - `model` ModelConfig
    - `provider` 'anthropic' | 'openai' | 'google' | 'gateway' | 'custom-openai' — LLM provider.
    - `model` string — Model identifier (e.g. "gemini-3-flash-preview", "claude-sonnet-4-6").
  - `subAgentModel` ModelConfig
    - `provider` 'anthropic' | 'openai' | 'google' | 'gateway' | 'custom-openai' — LLM provider.
    - `model` string — Model identifier (e.g. "gemini-3-flash-preview", "claude-sonnet-4-6").
  - `maxSteps` integer — Maximum agent steps before stopping.
  - `skills` string[] — Skills to pre-load for this run.
  - `skillInstructions` object — Per-skill custom instructions. Keys are skill names, values are instruction strings appended when the skill is loaded.
  - `subAgents` SubAgentConfig[] — Sub-agents available during this run. Each sub-agent becomes a tool the orchestrator can delegate tasks to.
    - `id` string, required — Unique identifier for this sub-agent (used as the tool name suffix).
    - `name` string, required — Human-readable name shown in the tool description.
    - `description` string, required — What this sub-agent does. Included in the tool description for the orchestrator.
    - `instructions` string — Custom instructions appended to the sub-agent's system prompt.
    - `model` ModelConfig
      - `provider` 'anthropic' | 'openai' | 'google' | 'gateway' | 'custom-openai' — LLM provider.
      - `model` string — Model identifier (e.g. "gemini-3-flash-preview", "claude-sonnet-4-6").
    - `tools` string[] — Firecrawl tools available to this sub-agent.
    - `skills` string[] — Skills to pre-load for this sub-agent.
    - `maxSteps` integer — Maximum steps before the sub-agent stops.
  - `exportSkill` boolean — When true, post-processes the run into a reusable skill package (SKILL.md + workflow.mjs + schema.json) returned in the response.

## Response `200`

Successful response

- RunResponse
  - `text` string — The agent's final text response.
  - `data` string — Formatted output (present when format was specified).
  - `format` 'json' | 'markdown' | 'text' — The format of the data field.
  - `durationMs` integer — Wall-clock duration of the run in milliseconds.
  - `model` string — Model that produced this response, as "provider:id".
  - `steps` StepDetail[]
    - `text` string
    - `toolCalls` object[]
      - `name` string
      - `input` object
    - `toolResults` object[]
      - `name` string
      - `output` object
  - `usage` Usage
    - `inputTokens` integer
    - `outputTokens` integer
    - `totalTokens` integer
  - `exportedSkill` ExportedSkill — A reusable skill package generated from the run's tool call history. Present when exportSkill=true in the request.
    - `name` string — Slug identifier for the skill.
    - `skillMd` string — Full SKILL.md content with frontmatter.
    - `workflow` string — Deterministic workflow.mjs script content.
    - `schema` string — Expected output schema.json content.

## Other responses

- `400` — Bad request
- `500` — Server error

---

[API](https://skmtc.net/firecrawl/apis/firecrawl-agent-api.md) · [All operations](https://skmtc.net/firecrawl/apis/firecrawl-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/firecrawl/firecrawl-agent-api/versions/0c3f2f357b0a/schema)