Agent

Start an agent task for agentic data extraction

curl --request POST \
  --url https://api.firecrawl.dev/v2/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "urls": [
    "<string>"
  ],
  "schema": {},
  "maxCredits": 123,
  "strictConstrainToURLs": true,
  "model": "spark-2",
  "threatProtection": {
    "riskScoreThreshold": 75,
    "blacklist": [
      "<string>"
    ],
    "whitelist": [
      "<string>"
    ],
    "blockedTlds": [
      "<string>"
    ]
  },
  "threadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "mode": "extract",
  "zeroDataRetention": false,
  "safe": true,
  "exchange": {
    "enabled": true,
    "toolkits": [
      "<string>"
    ],
    "maxCalls": 16,
    "requireApproval": false,
    "onTermsRequired": "skip"
  }
}
'

import requests

url = "https://api.firecrawl.dev/v2/agent"

payload = {
    "prompt": "<string>",
    "urls": ["<string>"],
    "schema": {},
    "maxCredits": 123,
    "strictConstrainToURLs": True,
    "model": "spark-2",
    "threatProtection": {
        "riskScoreThreshold": 75,
        "blacklist": ["<string>"],
        "whitelist": ["<string>"],
        "blockedTlds": ["<string>"]
    },
    "threadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "mode": "extract",
    "zeroDataRetention": False,
    "safe": True,
    "exchange": {
        "enabled": True,
        "toolkits": ["<string>"],
        "maxCalls": 16,
        "requireApproval": False,
        "onTermsRequired": "skip"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    urls: ['<string>'],
    schema: {},
    maxCredits: 123,
    strictConstrainToURLs: true,
    model: 'spark-2',
    threatProtection: {
      riskScoreThreshold: 75,
      blacklist: ['<string>'],
      whitelist: ['<string>'],
      blockedTlds: ['<string>']
    },
    threadId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    mode: 'extract',
    zeroDataRetention: false,
    safe: true,
    exchange: {
      enabled: true,
      toolkits: ['<string>'],
      maxCalls: 16,
      requireApproval: false,
      onTermsRequired: 'skip'
    }
  })
};

fetch('https://api.firecrawl.dev/v2/agent', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firecrawl.dev/v2/agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'urls' => [
        '<string>'
    ],
    'schema' => [
        
    ],
    'maxCredits' => 123,
    'strictConstrainToURLs' => true,
    'model' => 'spark-2',
    'threatProtection' => [
        'riskScoreThreshold' => 75,
        'blacklist' => [
                '<string>'
        ],
        'whitelist' => [
                '<string>'
        ],
        'blockedTlds' => [
                '<string>'
        ]
    ],
    'threadId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'mode' => 'extract',
    'zeroDataRetention' => false,
    'safe' => true,
    'exchange' => [
        'enabled' => true,
        'toolkits' => [
                '<string>'
        ],
        'maxCalls' => 16,
        'requireApproval' => false,
        'onTermsRequired' => 'skip'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firecrawl.dev/v2/agent"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"schema\": {},\n  \"maxCredits\": 123,\n  \"strictConstrainToURLs\": true,\n  \"model\": \"spark-2\",\n  \"threatProtection\": {\n    \"riskScoreThreshold\": 75,\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"whitelist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ]\n  },\n  \"threadId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"mode\": \"extract\",\n  \"zeroDataRetention\": false,\n  \"safe\": true,\n  \"exchange\": {\n    \"enabled\": true,\n    \"toolkits\": [\n      \"<string>\"\n    ],\n    \"maxCalls\": 16,\n    \"requireApproval\": false,\n    \"onTermsRequired\": \"skip\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firecrawl.dev/v2/agent")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"schema\": {},\n  \"maxCredits\": 123,\n  \"strictConstrainToURLs\": true,\n  \"model\": \"spark-2\",\n  \"threatProtection\": {\n    \"riskScoreThreshold\": 75,\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"whitelist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ]\n  },\n  \"threadId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"mode\": \"extract\",\n  \"zeroDataRetention\": false,\n  \"safe\": true,\n  \"exchange\": {\n    \"enabled\": true,\n    \"toolkits\": [\n      \"<string>\"\n    ],\n    \"maxCalls\": 16,\n    \"requireApproval\": false,\n    \"onTermsRequired\": \"skip\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v2/agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"schema\": {},\n  \"maxCredits\": 123,\n  \"strictConstrainToURLs\": true,\n  \"model\": \"spark-2\",\n  \"threatProtection\": {\n    \"riskScoreThreshold\": 75,\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"whitelist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ]\n  },\n  \"threadId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"mode\": \"extract\",\n  \"zeroDataRetention\": false,\n  \"safe\": true,\n  \"exchange\": {\n    \"enabled\": true,\n    \"toolkits\": [\n      \"<string>\"\n    ],\n    \"maxCalls\": 16,\n    \"requireApproval\": false,\n    \"onTermsRequired\": \"skip\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "threadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "threadTurn": 123
}

{
  "error": "Invalid JSON schema: ..."
}

{
  "error": "Payment required to access this resource."
}

{
  "error": "This URL (https://example.com) is blocked by your organization's threat protection policy (rule: blocklist). If you believe this is a mistake, contact your organization administrator to adjust the policy (e.g. whitelist the domain)."
}

{
  "error": "Rate limit exceeded."
}

{
  "error": "Failed to passthrough agent request."
}

POST

agent

Start an agent task for agentic data extraction

curl --request POST \
  --url https://api.firecrawl.dev/v2/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "urls": [
    "<string>"
  ],
  "schema": {},
  "maxCredits": 123,
  "strictConstrainToURLs": true,
  "model": "spark-2",
  "threatProtection": {
    "riskScoreThreshold": 75,
    "blacklist": [
      "<string>"
    ],
    "whitelist": [
      "<string>"
    ],
    "blockedTlds": [
      "<string>"
    ]
  },
  "threadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "mode": "extract",
  "zeroDataRetention": false,
  "safe": true,
  "exchange": {
    "enabled": true,
    "toolkits": [
      "<string>"
    ],
    "maxCalls": 16,
    "requireApproval": false,
    "onTermsRequired": "skip"
  }
}
'

import requests

url = "https://api.firecrawl.dev/v2/agent"

payload = {
    "prompt": "<string>",
    "urls": ["<string>"],
    "schema": {},
    "maxCredits": 123,
    "strictConstrainToURLs": True,
    "model": "spark-2",
    "threatProtection": {
        "riskScoreThreshold": 75,
        "blacklist": ["<string>"],
        "whitelist": ["<string>"],
        "blockedTlds": ["<string>"]
    },
    "threadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "mode": "extract",
    "zeroDataRetention": False,
    "safe": True,
    "exchange": {
        "enabled": True,
        "toolkits": ["<string>"],
        "maxCalls": 16,
        "requireApproval": False,
        "onTermsRequired": "skip"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    urls: ['<string>'],
    schema: {},
    maxCredits: 123,
    strictConstrainToURLs: true,
    model: 'spark-2',
    threatProtection: {
      riskScoreThreshold: 75,
      blacklist: ['<string>'],
      whitelist: ['<string>'],
      blockedTlds: ['<string>']
    },
    threadId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    mode: 'extract',
    zeroDataRetention: false,
    safe: true,
    exchange: {
      enabled: true,
      toolkits: ['<string>'],
      maxCalls: 16,
      requireApproval: false,
      onTermsRequired: 'skip'
    }
  })
};

fetch('https://api.firecrawl.dev/v2/agent', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firecrawl.dev/v2/agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'urls' => [
        '<string>'
    ],
    'schema' => [
        
    ],
    'maxCredits' => 123,
    'strictConstrainToURLs' => true,
    'model' => 'spark-2',
    'threatProtection' => [
        'riskScoreThreshold' => 75,
        'blacklist' => [
                '<string>'
        ],
        'whitelist' => [
                '<string>'
        ],
        'blockedTlds' => [
                '<string>'
        ]
    ],
    'threadId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'mode' => 'extract',
    'zeroDataRetention' => false,
    'safe' => true,
    'exchange' => [
        'enabled' => true,
        'toolkits' => [
                '<string>'
        ],
        'maxCalls' => 16,
        'requireApproval' => false,
        'onTermsRequired' => 'skip'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firecrawl.dev/v2/agent"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"schema\": {},\n  \"maxCredits\": 123,\n  \"strictConstrainToURLs\": true,\n  \"model\": \"spark-2\",\n  \"threatProtection\": {\n    \"riskScoreThreshold\": 75,\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"whitelist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ]\n  },\n  \"threadId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"mode\": \"extract\",\n  \"zeroDataRetention\": false,\n  \"safe\": true,\n  \"exchange\": {\n    \"enabled\": true,\n    \"toolkits\": [\n      \"<string>\"\n    ],\n    \"maxCalls\": 16,\n    \"requireApproval\": false,\n    \"onTermsRequired\": \"skip\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.firecrawl.dev/v2/agent")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"schema\": {},\n  \"maxCredits\": 123,\n  \"strictConstrainToURLs\": true,\n  \"model\": \"spark-2\",\n  \"threatProtection\": {\n    \"riskScoreThreshold\": 75,\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"whitelist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ]\n  },\n  \"threadId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"mode\": \"extract\",\n  \"zeroDataRetention\": false,\n  \"safe\": true,\n  \"exchange\": {\n    \"enabled\": true,\n    \"toolkits\": [\n      \"<string>\"\n    ],\n    \"maxCalls\": 16,\n    \"requireApproval\": false,\n    \"onTermsRequired\": \"skip\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v2/agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"schema\": {},\n  \"maxCredits\": 123,\n  \"strictConstrainToURLs\": true,\n  \"model\": \"spark-2\",\n  \"threatProtection\": {\n    \"riskScoreThreshold\": 75,\n    \"blacklist\": [\n      \"<string>\"\n    ],\n    \"whitelist\": [\n      \"<string>\"\n    ],\n    \"blockedTlds\": [\n      \"<string>\"\n    ]\n  },\n  \"threadId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"mode\": \"extract\",\n  \"zeroDataRetention\": false,\n  \"safe\": true,\n  \"exchange\": {\n    \"enabled\": true,\n    \"toolkits\": [\n      \"<string>\"\n    ],\n    \"maxCalls\": 16,\n    \"requireApproval\": false,\n    \"onTermsRequired\": \"skip\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "threadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "threadTurn": 123
}

{
  "error": "Invalid JSON schema: ..."
}

{
  "error": "Payment required to access this resource."
}

{
  "error": "This URL (https://example.com) is blocked by your organization's threat protection policy (rule: blocklist). If you believe this is a mistake, contact your organization administrator to adjust the policy (e.g. whitelist the domain)."
}

{
  "error": "Rate limit exceeded."
}

{
  "error": "Failed to passthrough agent request."
}

Are you an AI agent that needs a Firecrawl API key? See firecrawl.dev/agent-onboarding/SKILL.md for automated onboarding instructions.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

prompt

string

required

The prompt describing what data to extract

Maximum string length: 10000

urls

string<uri>[]

Optional list of URLs to constrain the agent to

schema

object

Optional JSON schema to structure the extracted data

maxCredits

number

Maximum credits to spend on this agent task. Defaults to 2500 if not set. Values above 2,500 are always billed as paid requests.

strictConstrainToURLs

boolean

If true, agent will only visit URLs provided in the urls array

model

enum<string>

default:spark-2

The model to use for the agent task. spark-2 is the default and the model every run executes on. The Spark 1 model names remain accepted for backwards compatibility but are deprecated and route to spark-2.

Available options:

spark-2,

spark-1-mini,

spark-1-pro

effort

enum<string>

Reasoning budget for the agent task. Every run executes on spark-2, so effort can be sent with or without model.

Available options:

low,

medium,

high

webhook

object

A webhook specification object. Subscribes to agent lifecycle events (agent.started, agent.action, agent.completed, agent.failed, agent.cancelled).

Show child attributes

auditMetadata

object

User attribution included with SIEM logging events when SIEM Logging is enabled for the organization.

Show child attributes

threatProtection

Threat Protection Override · object

Per-request Threat Protection override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, mode may not be set to off.

Show child attributes

threadId

string<uuid>

Continue an existing thread: pass the threadId an earlier run returned, and this request runs as that thread's next turn. Omitted urls, schema, effort, mode and exchange settings carry over from the previous turn. Omit threadId to start a new thread.

mode

enum<string>

default:extract

extract returns the complete structured result in data every turn. chat lets a follow-up that asks for no new data get a short reply in message instead of a re-run. exchange.requireApproval needs chat on the same request. Omitted on a follow-up turn keeps the thread's mode.

Available options:

extract,

chat

zeroDataRetention

boolean

default:false

Run the agent with Zero Data Retention: Firecrawl keeps no prompt, result or step content in logs or storage, only billing and status metadata. The result is kept for 24 hours for retrieval, then deleted. Requires Scrape ZDR and Search ZDR to be enabled for your team, otherwise the request returns 400 zdr_not_enabled. Cannot be combined with threadId. With exchange, only capabilities that support ZDR are used. See Zero Data Retention.

location

object

Proxy country for every request the agent makes during the run: scrapes, batch scrapes and browser sessions go out from this country, and the agent cannot change it. Search results are localized to the country. Omitted on a follow-up turn keeps the thread's country. See Choosing a location.

Show child attributes

safe

boolean

When true, every web search the agent makes during the run filters explicit content, the same filter as the search endpoint's safe option. Pages the agent scrapes or opens in a browser are not filtered. Omit to keep the default behavior, which does not apply the filter. Omitted on a follow-up turn keeps the thread's setting; false turns it off.

exchange

object

Let the agent call your team's Alexandria data providers during the run. Without this object the run uses the web only (a follow-up turn inherits the previous turn's settings). See Use your connected Alexandria tools.

Show child attributes

Response

Agent task started successfully

success

boolean

string<uuid>

threadId

string<uuid>

The thread this run belongs to. Pass it as threadId to continue the thread.

threadTurn

integer

This run's turn in the thread, starting at 1.

Using the API

Search Endpoints

Scrape Endpoints

Interact / Browser Sandbox Endpoints

Research Index Endpoints

Developer Index Endpoints

Government Index Endpoints

Map Endpoints

Parse Endpoints

Crawl Endpoints

Monitor Endpoints

Agent Endpoints

Feedback Endpoints

Agentic Debugging Endpoints

Account Endpoints

Webhook Payloads

Firecrawl for Platforms

Authentication

Authorizations

Body

Response