Deep Research

Start a deep research operation on a query

curl --request POST \
  --url https://api.firecrawl.dev/v1/deep-research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "maxDepth": 7,
  "timeLimit": 300,
  "maxUrls": 20,
  "analysisPrompt": "<string>",
  "systemPrompt": "<string>",
  "formats": [
    "markdown"
  ],
  "jsonOptions": {
    "schema": {},
    "systemPrompt": "<string>",
    "prompt": "<string>"
  }
}
'

import requests

url = "https://api.firecrawl.dev/v1/deep-research"

payload = {
    "query": "<string>",
    "maxDepth": 7,
    "timeLimit": 300,
    "maxUrls": 20,
    "analysisPrompt": "<string>",
    "systemPrompt": "<string>",
    "formats": ["markdown"],
    "jsonOptions": {
        "schema": {},
        "systemPrompt": "<string>",
        "prompt": "<string>"
    }
}
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({
    query: '<string>',
    maxDepth: 7,
    timeLimit: 300,
    maxUrls: 20,
    analysisPrompt: '<string>',
    systemPrompt: '<string>',
    formats: ['markdown'],
    jsonOptions: {schema: {}, systemPrompt: '<string>', prompt: '<string>'}
  })
};

fetch('https://api.firecrawl.dev/v1/deep-research', 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/v1/deep-research",
  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([
    'query' => '<string>',
    'maxDepth' => 7,
    'timeLimit' => 300,
    'maxUrls' => 20,
    'analysisPrompt' => '<string>',
    'systemPrompt' => '<string>',
    'formats' => [
        'markdown'
    ],
    'jsonOptions' => [
        'schema' => [
                
        ],
        'systemPrompt' => '<string>',
        'prompt' => '<string>'
    ]
  ]),
  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/v1/deep-research"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"maxDepth\": 7,\n  \"timeLimit\": 300,\n  \"maxUrls\": 20,\n  \"analysisPrompt\": \"<string>\",\n  \"systemPrompt\": \"<string>\",\n  \"formats\": [\n    \"markdown\"\n  ],\n  \"jsonOptions\": {\n    \"schema\": {},\n    \"systemPrompt\": \"<string>\",\n    \"prompt\": \"<string>\"\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/v1/deep-research")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"maxDepth\": 7,\n  \"timeLimit\": 300,\n  \"maxUrls\": 20,\n  \"analysisPrompt\": \"<string>\",\n  \"systemPrompt\": \"<string>\",\n  \"formats\": [\n    \"markdown\"\n  ],\n  \"jsonOptions\": {\n    \"schema\": {},\n    \"systemPrompt\": \"<string>\",\n    \"prompt\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v1/deep-research")

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  \"query\": \"<string>\",\n  \"maxDepth\": 7,\n  \"timeLimit\": 300,\n  \"maxUrls\": 20,\n  \"analysisPrompt\": \"<string>\",\n  \"systemPrompt\": \"<string>\",\n  \"formats\": [\n    \"markdown\"\n  ],\n  \"jsonOptions\": {\n    \"schema\": {},\n    \"systemPrompt\": \"<string>\",\n    \"prompt\": \"<string>\"\n  }\n}"

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

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

{
  "success": false,
  "error": "Invalid parameters provided"
}

POST

deep-research

Start a deep research operation on a query

curl --request POST \
  --url https://api.firecrawl.dev/v1/deep-research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "maxDepth": 7,
  "timeLimit": 300,
  "maxUrls": 20,
  "analysisPrompt": "<string>",
  "systemPrompt": "<string>",
  "formats": [
    "markdown"
  ],
  "jsonOptions": {
    "schema": {},
    "systemPrompt": "<string>",
    "prompt": "<string>"
  }
}
'

import requests

url = "https://api.firecrawl.dev/v1/deep-research"

payload = {
    "query": "<string>",
    "maxDepth": 7,
    "timeLimit": 300,
    "maxUrls": 20,
    "analysisPrompt": "<string>",
    "systemPrompt": "<string>",
    "formats": ["markdown"],
    "jsonOptions": {
        "schema": {},
        "systemPrompt": "<string>",
        "prompt": "<string>"
    }
}
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({
    query: '<string>',
    maxDepth: 7,
    timeLimit: 300,
    maxUrls: 20,
    analysisPrompt: '<string>',
    systemPrompt: '<string>',
    formats: ['markdown'],
    jsonOptions: {schema: {}, systemPrompt: '<string>', prompt: '<string>'}
  })
};

fetch('https://api.firecrawl.dev/v1/deep-research', 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/v1/deep-research",
  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([
    'query' => '<string>',
    'maxDepth' => 7,
    'timeLimit' => 300,
    'maxUrls' => 20,
    'analysisPrompt' => '<string>',
    'systemPrompt' => '<string>',
    'formats' => [
        'markdown'
    ],
    'jsonOptions' => [
        'schema' => [
                
        ],
        'systemPrompt' => '<string>',
        'prompt' => '<string>'
    ]
  ]),
  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/v1/deep-research"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"maxDepth\": 7,\n  \"timeLimit\": 300,\n  \"maxUrls\": 20,\n  \"analysisPrompt\": \"<string>\",\n  \"systemPrompt\": \"<string>\",\n  \"formats\": [\n    \"markdown\"\n  ],\n  \"jsonOptions\": {\n    \"schema\": {},\n    \"systemPrompt\": \"<string>\",\n    \"prompt\": \"<string>\"\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/v1/deep-research")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"maxDepth\": 7,\n  \"timeLimit\": 300,\n  \"maxUrls\": 20,\n  \"analysisPrompt\": \"<string>\",\n  \"systemPrompt\": \"<string>\",\n  \"formats\": [\n    \"markdown\"\n  ],\n  \"jsonOptions\": {\n    \"schema\": {},\n    \"systemPrompt\": \"<string>\",\n    \"prompt\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v1/deep-research")

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  \"query\": \"<string>\",\n  \"maxDepth\": 7,\n  \"timeLimit\": 300,\n  \"maxUrls\": 20,\n  \"analysisPrompt\": \"<string>\",\n  \"systemPrompt\": \"<string>\",\n  \"formats\": [\n    \"markdown\"\n  ],\n  \"jsonOptions\": {\n    \"schema\": {},\n    \"systemPrompt\": \"<string>\",\n    \"prompt\": \"<string>\"\n  }\n}"

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

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

{
  "success": false,
  "error": "Invalid parameters provided"
}

The Deep Research endpoint enables AI-powered deep research and analysis on any topic. Simply provide a research query, and Firecrawl will autonomously explore the web, gather relevant information, and synthesize findings into comprehensive insights.

This is the legacy v1 Deep Research API. For new research agents, use the current Deep Research use case, which is built from Search and Scrape.

Looking for the status endpoint? Check out the Deep Research Status endpoint.

Response Structure

The response includes:

activities: List of research activities with:
- type: Activity type (‘search’, ‘extract’, ‘analyze’, ‘reasoning’, ‘synthesis’, ‘thought’)
- status: Status (‘processing’, ‘complete’, ‘error’)
- message: Description of activity/finding
- timestamp: ISO timestamp
- depth: Research depth level
sources: Referenced URLs with:
- title: Source title
- description: Source description
- url: Source URL
- icon: Source favicon
finalAnalysis: Comprehensive analysis (when completed)
status: Overall status (‘processing’, ‘completed’, ‘failed’)
currentDepth: Current research depth
maxDepth: Maximum research depth
totalUrls: Number of URLs analyzed
expiresAt: ISO timestamp when results expire

Limitations

Best suited for topics with publicly available information
Research jobs limited to 10 minutes maximum
Manual verification recommended for critical information
Alpha feature - methodology and output may evolve

Billing

Billing is based on number of URLs analyzed:

Each URL = 1 credit
Control usage with maxUrls parameter

Authorizations

Authorization

string

header

required

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

Body

application/json

query

string

required

The query to research

maxDepth

integer

default:7

Maximum depth of research iterations

Required range: 1 <= x <= 12

timeLimit

integer

default:300

Time limit in seconds

Required range: 30 <= x <= 600

maxUrls

integer

default:20

Maximum number of URLs to analyze

Required range: 1 <= x <= 1000

analysisPrompt

string

The prompt to use for the final analysis. Useful to format the final analysis markdown in a specific way.

systemPrompt

string

The system prompt to use for the research agent. Useful to steer the research agent to a specific direction.

formats

enum<string>[]

Available options:

markdown,

json

jsonOptions

object

Options for JSON output

Show child attributes

Response

Research job started successfully

success

boolean

Example:

true

string<uuid>

ID of the research job

Using the API

Search Endpoints

Scrape Endpoints

Interact Endpoints

Research Index Endpoints

Map Endpoints

Parse Endpoints

Crawl Endpoints

Monitor Endpoints

Feedback Endpoints

Agentic Debugging Endpoints

Account Endpoints

Webhook Payloads

Partner Integration

Response Structure

Limitations

Billing

Authorizations

Body

Response

​Response Structure

​Limitations

​Billing

Authorizations

Body

Response

Response Structure

Limitations

Billing