Firecrawl API SOP

Appearance

Search ​

Core Feature

Search the web and optionally scrape results in one operation.

Overview ​

The Search API performs web searches across multiple source types (web, news, images) and content categories (GitHub, research, PDF). Optionally scrape full content from each result.

Basic Usage ​

python
from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

results = firecrawl.search(
    query="firecrawl web scraping",
    limit=5
)
javascript
import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const results = await firecrawl.search("firecrawl web scraping", { limit: 5 });

Response Structure ​

json
{
  "success": true,
  "data": {
    "web": [
      {"url": "...", "title": "...", "description": "...", "position": 1}
    ],
    "images": [
      {"title": "...", "imageUrl": "...", "imageWidth": 5814, "imageHeight": 1200, "url": "...", "position": 1}
    ],
    "news": [
      {"title": "...", "url": "...", "snippet": "...", "date": "3 months ago", "position": 1}
    ]
  }
}

Sources (Result Types) ​

Control which types of results you get:

python
# Web results (default)
results = firecrawl.search("best web scraping tools", sources=["web"])

# News results
results = firecrawl.search("AI news", sources=["news"])

# Image results
results = firecrawl.search("architecture sunset", sources=["images"])

# Multiple sources
results = firecrawl.search("firecrawl", sources=["web", "news", "images"])

The limit parameter applies per source type when multiple sources are specified.

Categories (Content-Filtered Search) ​

Search specific content ecosystems:

python
# GitHub repos, code, issues, docs
results = firecrawl.search(
    query="python web scraping",
    categories=["github"],
    limit=10
)

# Academic research (arXiv, Nature, IEEE, PubMed)
results = firecrawl.search(
    query="machine learning transformers",
    categories=["research"],
    limit=10
)

# PDF documents
results = firecrawl.search(
    query="annual report 2024",
    categories=["pdf"],
    limit=10
)

# Combined categories
results = firecrawl.search(
    query="neural networks",
    categories=["github", "research"],
    limit=15
)

Results include a category field indicating the source.

Find images by exact or minimum resolution:

python
# Exact resolution
results = firecrawl.search(
    query="sunset imagesize:1920x1080",
    sources=["images"]
)

# Minimum resolution
results = firecrawl.search(
    query="mountain wallpaper larger:2560x1440",
    sources=["images"]
)

Time-Based Filtering ​

Filter results by time with the tbs parameter:

python
# Past hour
results = firecrawl.search("breaking news", tbs="qdr:h")

# Past 24 hours
results = firecrawl.search("tech updates", tbs="qdr:d")

# Past week
results = firecrawl.search("AI developments", tbs="qdr:w")

# Past month
results = firecrawl.search("startup funding", tbs="qdr:m")

# Past year
results = firecrawl.search("web scraping tools", tbs="qdr:y")

# Sort by date (newest first)
results = firecrawl.search("firecrawl updates", tbs="sbd:1")

# Custom date range
results = firecrawl.search(
    "firecrawl",
    tbs="cdr:1,cd_min:12/1/2024,cd_max:12/31/2024"
)

INFO

tbs only applies to web source results, not news or images.

Search with Content Scraping ​

Scrape full content from each search result:

python
results = firecrawl.search(
    "firecrawl features",
    limit=3,
    scrape_options={
        "formats": ["markdown", "links"]
    }
)

for result in results:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Content: {result['markdown']}")

All scrape endpoint options are supported via scrapeOptions (except Agent and Change Tracking).

Location ​

Target specific locations:

python
results = firecrawl.search("web hosting", location="Germany")

Custom Timeout ​

python
results = firecrawl.search("complex query", limit=10, timeout=30000)  # 30s in ms

Cost Control Tips ​

  • Set parsers: [] if PDF parsing not needed
  • Use proxy: "basic" instead of "enhanced" or "auto"
  • Lower the limit parameter
  • Only add scrapeOptions when you need full page content

Cost ​

  • Search: 2 credits per 10 results
  • With scraping: +1 credit per result scraped (standard scrape costs)

Next: Map →