Introduction

Firecrawl API Reference (v2)

Features

Scrape

Extract content from any webpage in markdown or json format.

Crawl

Crawl entire websites, extract their content and metadata.

Map

Get a complete list of URLs from any website quickly and reliably.

Search

Search the web and get full page content in any format.

Agentic Features

Extract

Extract structured data from entire webpages using natural language.

Base URL

All requests contain the following base URL:

https://api.firecrawl.dev 

Authentication

For authentication, it’s required to include an Authorization header. The header should contain Bearer fc-123456789, where fc-123456789 represents your API Key.

Authorization: Bearer fc-123456789

​

Response codes

Firecrawl employs conventional HTTP status codes to signify the outcome of your requests.

Typically, 2xx HTTP status codes denote success, 4xx codes represent failures related to the user, and 5xx codes signal infrastructure problems.

Status	Description
200	Request was successful.
400	Verify the correctness of the parameters.
401	The API key was not provided.
402	Payment required
404	The requested resource could not be located.
429	The rate limit has been surpassed.
5xx	Signifies a server error with Firecrawl.

Refer to the Error Codes section for a detailed explanation of all potential API errors.

​

Rate limit

The Firecrawl API has a rate limit to ensure the stability and reliability of the service. The rate limit is applied to all endpoints and is based on the number of requests made within a specific time frame.

When you exceed the rate limit, you will receive a 429 response code with a Retry-After header indicating how many seconds to wait before retrying.

Handling rate limits

When you encounter a 429 error, implement exponential backoff to retry your requests gracefully:

1. Read the Retry-After response header (value in seconds)
2. Wait for the specified duration before retrying
3. For subsequent retries, use exponential backoff: wait initial_delay × (backoff_factor ^ retry_count)
4. Start with an initial delay of 1 second and a backoff factor of 2 (e.g., 1s, 2s, 4s, 8s, etc.)

Example:

import time
import requests

def make_request_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers)
        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get('Retry-After', 2 ** attempt))
        print(f"Rate limited. Waiting {retry_after} seconds...")
        time.sleep(retry_after)

    raise Exception("Max retries exceeded")