Python Agent Quickstart

Canonical Firecrawl Python quickstart for external agents using search, scrape, and interact.

Firecrawl Python Agent Quickstart

This file is the canonical quickstart for external agents integrating Firecrawl via the Python SDK. It is generated from SDK source and OpenAPI spec.

Install

pip install firecrawl-py

Authenticate

from firecrawl import Firecrawl

client = Firecrawl(api_key="fc-YOUR_API_KEY")

The API key can also be set via the FIRECRAWL_API_KEY environment variable. If omitted, the client falls back to keyless free tier (rate-limited per IP).

Constructor options: api_key (str), api_url (str, default "https://api.firecrawl.dev"), timeout (float), max_retries (int, default 3), backoff_factor (float, default 0.5).

An async client is also available: from firecrawl import AsyncFirecrawl.

When To Use What

• search: Use when you start with a query and need to discover relevant URLs and their content. Returns results from web, news, and image sources.
• scrape: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats.
• interact: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session.

Search

Why use it

Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction.

Preferred SDK method

client.search(query, **kwargs)

Example

results = client.search(
    "firecrawl web scraping API",
    limit=5,
    scrape_options={"formats": ["markdown"]},
)

for item in results.web or []:
    print(item.get("title"), item.get("url"))

Parameters

Parameter	Type	Description
query	str	The search query (first argument, required).
sources	list[str]	Sources to search: "web", "news", "images".
categories	list[str]	Filter by category: "github", "research", "pdf", "developer".
include_domains	list[str]	Restrict results to these domains. Cannot be used with exclude_domains.
exclude_domains	list[str]	Exclude results from these domains. Cannot be used with include_domains.
limit	int	Maximum number of results. Server default: 10.
tbs	str	Time-based search filter (e.g. "qdr:d" for past day, "qdr:w" for past week).
location	str	Location string for geo-targeted search.
ignore_invalid_urls	bool	Ignore invalid URLs in results.
timeout	int	Timeout in milliseconds. Server default: 60000.
highlights	bool	Generate query-relevant highlights. Default: True.
scrape_options	ScrapeOptions	Nested scrape configuration applied to each result.
enterprise	list[str]	Enterprise search options for ZDR.
threat_protection	ThreatProtectionOptions	Per-request threat protection overrides.
integration	str	Integration identifier.

Return type

SearchData with attributes: web, news, images, developer. Each is a list of result dicts or None. Access results via results.web, not results.data.

Scrape

Why use it

Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more.

Preferred SDK method

client.scrape(url, **kwargs)

Example

doc = client.scrape(
    "https://example.com",
    formats=["markdown", "html"],
    only_main_content=True,
)

print(doc.markdown)

Parameters

Parameter	Type	Description
url	str	The URL to scrape (first argument, required).
formats	list	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "json", "attributes", "branding", "product", "menu", "audio", "video", or typed dicts. Server default: ["markdown"].
only_main_content	bool	Strip boilerplate, keep main content only. Server default: True.
headers	dict[str, str]	Custom HTTP headers to send with the request.
include_tags	list[str]	HTML tags to exclusively include.
exclude_tags	list[str]	HTML tags to exclude.
timeout	int	Timeout in milliseconds. Min: 1000, max: 300000. Server default: 60000.
wait_for	int	Delay in milliseconds before fetching content.
mobile	bool	Emulate mobile device.
parsers	list	Parser configurations (e.g. "pdf" or {"type": "pdf", "mode": "auto"}). Server default: ["pdf"].
actions	list[dict]	Browser automation actions. See Actions table below.
location	Location	Location settings: {"country": "US", "languages": ["en-US"]}.
skip_tls_verification	bool	Skip TLS certificate verification.
remove_base64_images	bool	Remove base64 images from markdown output. Server default: True.
fast_mode	bool	Enable fast mode for faster scrapes.
block_ads	bool	Block advertisements and cookie popups. Server default: True.
proxy	str	Proxy tier: "basic", "stealth", "enhanced", "auto". Server default: "auto".
max_age	int	Use cached result if younger than this many milliseconds. Server default: 172800000 (2 days).
store_in_cache	bool	Cache the scrape result. Server default: True.
lockdown	bool	Only serve cached results, never make outbound requests.
threat_protection	ThreatProtectionOptions	Per-request threat protection overrides.
audit_metadata	AuditMetadata	User attribution for SIEM logging: {"username": "..."}.
profile	dict	Persistent browser profile: {"name": "...", "save_changes": True}.
integration	str	Integration identifier.
use_mock	str	Use mock data.

Actions

Type	Fields
wait	{"type": "wait", "milliseconds": int} or {"type": "wait", "selector": str}
screenshot	{"type": "screenshot", "fullPage": bool, "quality": int}
click	{"type": "click", "selector": str}
write	{"type": "write", "text": str}
press	{"type": "press", "key": str}
scroll	{"type": "scroll", "direction": "up" | "down", "selector": str}
scrape	{"type": "scrape"}
executeJavascript	{"type": "executeJavascript", "script": str}
pdf	{"type": "pdf", "format": str, "landscape": bool, "scale": float}

Interact

Why use it

Execute code or send natural-language prompts in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts.

Preferred SDK method

client.interact(job_id, code=None, *, prompt=None, language="node", timeout=None, origin=None)

Example

doc = client.scrape("https://example.com", formats=["markdown"])
job_id = doc.metadata.get("jobId")

result = client.interact(job_id, code="document.title", language="node")
print(result.stdout)

client.stop_interaction(job_id)

Parameters

Parameter	Type	Description
job_id	str	The scrape job ID (first argument, required).
code	str	Code to execute in the browser sandbox (positional).
prompt	str	Natural-language instruction for the browser agent (keyword-only).
language	str	Execution language: "python", "node", "bash". Default: "node".
timeout	int	Execution timeout in seconds. Range: 1-300. Server default: 30.
origin	str	Origin identifier for telemetry.

Either code or prompt must be provided. Use client.stop_interaction(job_id) to end the browser session.

Notes

• Naming style: All parameters use snake_case.
• Deprecated aliases: scrape_url() is deprecated in favor of scrape(). scrape_execute() is deprecated in favor of interact(). stop_interactive_browser() and delete_scrape_browser() are deprecated in favor of stop_interaction(). FirecrawlApp is deprecated in favor of Firecrawl.
• Async support: Use AsyncFirecrawl for async/await usage with the same method signatures.
• Search return type: Access results via results.web, results.news, results.images, results.developer. Accessing results.data raises AttributeError with guidance.

Source Of Truth

• /firecrawl/apps/python-sdk/firecrawl/client.py
• /firecrawl/apps/python-sdk/firecrawl/v2/client.py
• /firecrawl/apps/python-sdk/firecrawl/v2/types.py
• /firecrawl-docs/api-reference/v2-openapi.json