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",
  "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",
    "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',
    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',
    '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  \"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  \"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  \"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",
  "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",
    "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',
    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',
    '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  \"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  \"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  \"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

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

Authorizations

Body

Response