Python Agent Quickstart

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

Firecrawl Python Agent Quickstart

Canonical quickstart for external agents integrating Firecrawl with Python. Generated from SDK source and OpenAPI spec.

Install

pip install firecrawl-py

Requires Python 3.8+.

Authenticate

from firecrawl import Firecrawl

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

Or set the FIRECRAWL_API_KEY environment variable and omit api_key:

app = Firecrawl()

Constructor parameters:

Parameter	Type	Default
api_key	str	None (falls back to FIRECRAWL_API_KEY env var)
api_url	str	"https://api.firecrawl.dev"
timeout	float	None
max_retries	int	3
backoff_factor	float	0.5

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

When To Use What

• search: Start with a query, discover relevant URLs, and get their content in one call.
• scrape: You already have a URL and want its page content as markdown, HTML, JSON, or other formats.
• interact: The page needs clicks, form fills, or post-scrape browser actions on a live session.

Search

Why use it

Search the web for a query and get scraped content from the top results. Combines discovery and content extraction in one call.

Preferred SDK method

search(query, **kwargs)

Example

results = app.search("firecrawl web scraping", limit=5)

for result in results.web:
    print(result.title, result.url)
    print(result.markdown)

Parameters

Parameter	Type	Description
query	str	Required. Search query (max 500 chars).
limit	int	Max results per source type. Default: 5 (SDK default).
sources	list	Sources to search: "web", "news", "images", or Source objects.
categories	list	Category filters: "github", "research", "pdf", "developer".
include_domains	list[str]	Restrict to these domains. Cannot combine with exclude_domains.
exclude_domains	list[str]	Exclude these domains. Cannot combine with include_domains.
tbs	str	Time-based filter (e.g. "qdr:d" past day, "qdr:w" past week, "qdr:m" past month).
location	str	Geo-targeting location string.
ignore_invalid_urls	bool	Exclude invalid URLs from results.
timeout	int	Timeout in ms. Default: 300000.
highlights	bool	Generate query-relevant highlights.
scrape_options	ScrapeOptions	Scrape options applied to each result page.
enterprise	list[str]	Enterprise zero data retention options.
threat_protection	ThreatProtectionOptions	Per-request threat protection override.
integration	str	Integration identifier.

Response groups results by source: results.web, results.news, results.images, results.developer.

Scrape

Why use it

Get the content of a single URL as markdown, HTML, JSON, screenshots, or other formats.

Preferred SDK method

scrape(url, **kwargs)

Example

result = app.scrape("https://example.com", formats=["markdown", "links"], only_main_content=True)

print(result.markdown)
print(result.links)

Parameters

Parameter	Type	Description
url	str	Required. URL to scrape.
formats	list	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "changeTracking", "attributes", "branding", "product", "menu", "audio", "video". Also accepts format config dicts. Default: ["markdown"].
headers	dict[str, str]	Custom HTTP headers.
include_tags	list[str]	HTML tags to include.
exclude_tags	list[str]	HTML tags to exclude.
only_main_content	bool	Strip navbars, footers, boilerplate. Default: true.
timeout	int	Timeout in ms. Default: 60000. Min: 1000, Max: 300000.
wait_for	int	Extra delay in ms before fetching content.
mobile	bool	Emulate a mobile device.
parsers	list	File processing controls. Accepts "pdf" or {"type": "pdf", "mode": "fast"|"auto"|"ocr", "max_pages": int}.
actions	list	Browser actions before content capture: WaitAction, ClickAction, WriteAction, PressAction, ScrollAction, ScreenshotAction, ScrapeAction, ExecuteJavascriptAction, PDFAction.
location	Location	Geo settings with country and languages. Country defaults to "US".
skip_tls_verification	bool	Skip TLS certificate verification.
remove_base64_images	bool	Remove base64 images from markdown. Default: true.
fast_mode	bool	Enable fast mode.
block_ads	bool	Block ads and cookie popups. Default: true.
proxy	str	Proxy type: "basic", "stealth", "enhanced", "auto". Default: "auto".
max_age	int	Cache threshold in ms. Returns cached version if younger. Default: 2 days.
min_age	int	Cache-only mode minimum age in ms.
store_in_cache	bool	Store result in Firecrawl cache. Default: true.
lockdown	bool	Cache-only, no outbound requests.
redact_pii	bool | RedactPIIOptions	Redact PII. Pass True for defaults or a RedactPIIOptions object.
threat_protection	ThreatProtectionOptions	Threat protection override.
audit_metadata	AuditMetadata	SIEM logging with username field.
profile	dict	Persistent browser profile with name and optional save_changes.
integration	str	Integration identifier.

Interact

Why use it

Control a live browser session tied to a scrape job. Click buttons, fill forms, navigate, and extract dynamic content using code or natural-language prompts.

Preferred SDK method

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

Example

result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata.scrape_id

app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max")
response = app.interact(scrape_id, prompt="Click on the first result and tell me the price")
print(response.output)

app.stop_interaction(scrape_id)

Parameters

Parameter	Type	Description
job_id	str	Required. Scrape job ID from result.metadata.scrape_id.
code	str	Code to execute in the browser sandbox. One of code or prompt required.
prompt	str	Natural-language instruction. One of code or prompt required.
language	Literal["python", "node", "bash"]	Runtime for code execution. Default: "node".
timeout	int	Execution timeout in seconds. Min: 1, Max: 300.
origin	str	Origin label for telemetry.

Stop the session when done:

app.stop_interaction(scrape_id)

Notes

• Parameter names use snake_case (e.g. only_main_content, include_tags, scrape_options).
• include_domains and exclude_domains on search are mutually exclusive.
• FirecrawlApp is a deprecated alias for Firecrawl. Use Firecrawl.
• AsyncFirecrawlApp is a deprecated alias for AsyncFirecrawl.
• Deprecated method aliases (do not use in new code):
  • scrape_execute() → use interact()
  • stop_interactive_browser() / delete_scrape_browser() → use stop_interaction()
  • scrape_url() → use scrape()
  • crawl_url() → use crawl()
  • map_url() → use map()

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