Start Deep Research

Start a deep research operation on a query

POST /v1/deep-research

Start a deep research operation that analyzes a query in depth by iteratively searching, analyzing, and synthesizing information from multiple sources.

Authentication

This endpoint requires authentication using a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Request Body

query · string · required

The query to research

maxDepth · integer · default: 7

Maximum depth of research iterations. Must be between 1 and 12.

timeLimit · integer · default: 300

Time limit in seconds. Must be between 30 and 600.

maxUrls · integer · default: 20

Maximum number of URLs to analyze. Must be between 1 and 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 · array

Array of output formats. Options: markdown, json, branding. Default: ["markdown"]

jsonOptions · object

Options for JSON output

Show properties

schema · object

The schema to use for the JSON output. Must conform to JSON Schema.

systemPrompt · string

The system prompt to use for the JSON output

prompt · string

The prompt to use for the JSON output

Response

success · boolean

Indicates if the request was successful

id · string

ID of the research job (UUID format)

Example Request

cURL

curl -X POST https://api.firecrawl.dev/v1/deep-research \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Latest developments in quantum computing",
    "maxDepth": 5,
    "timeLimit": 180,
    "maxUrls": 15
  }'

Example Response

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

400 Bad Request · object

Invalid request parameters

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

Next Steps

After starting a research job, use the Get Research Status endpoint to check the progress and retrieve results.