---
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

## Changes

- **2026-07-17** `0c3f2f357b0a` — 1 info
  - added the optional property `model` to the response with the `200` status
- **2026-04-16** `a4a14d46dc98` — 1 breaking, 4 info
  - removed the enum value `csv` of the request property `format`
  - the `maxSteps` request property default value changed from `15` to `50`
  - the `maxSteps` request property's max was increased from `50.00` to `200.00`
  - added the optional property `durationMs` to the response with the `200` status
  - …1 more
- **2026-04-16** `ad5d8a76db33` — 6 breaking, 3 info
  - removed the enum value `acp` of the request property `model/provider`
  - removed the enum value `acp` of the request property `subAgentModel/provider`
  - removed the enum value `acp` of the request property `subAgents/items/model/provider`
  - removed the enum value `firecrawl` of the request property `model/provider`
  - …5 more
- **2026-04-06** `5bf2d1414408` — 8 info
  - added the new optional request property `exportSkill`
  - added the new optional request property `skillInstructions`
  - added the new optional request property `subAgents`
  - added the new `acp` enum value to the request property `model/provider`
  - …4 more
- …earlier changes not shown

[Full history](https://skmtc.dev/firecrawl/apis/firecrawl-agent-api/changes/run/post.md)

---

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