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 with Firecrawl using the Python SDK. It is generated from SDK source and OpenAPI spec.

Install

pip install firecrawl-py

Authenticate

from firecrawl import Firecrawl

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

The API key can also be set via the FIRECRAWL_API_KEY environment variable. Omitting the key uses the keyless free tier (rate-limited per IP).

Client options:

Option	Type	Default	Description
api_key	str	FIRECRAWL_API_KEY env var	API key for authentication
api_url	str	"https://api.firecrawl.dev"	Base URL for the API
timeout	float	None	Default request timeout in seconds
max_retries	int	3	Max automatic retries for transient failures
backoff_factor	float	0.5	Exponential backoff factor for retries

When To Use What

• search: Use when you start with a query and need to discover relevant pages. Returns ranked results with optional scraping of each result.
• scrape: Use when you already have a URL and want its content in markdown, HTML, JSON, or other formats.
• interact: Use when a page needs post-scrape browser actions — clicking, filling forms, running code, or prompting an AI agent in the browser.

Search

Why use it

Search the web for a query and get back ranked results. Optionally scrape each result page inline by passing scrape_options.

Preferred SDK method

app.search(query, **kwargs)

Example

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

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

Parameters

Parameter	Type	Description
query	str	Required. The search query (max 500 chars).
limit	int	Max results to return. Default: 5.
sources	list	Which result sources to include: "web", "news", "images".
categories	list	Filter results by category: "github", "research", "pdf", "developer".
include_domains	list[str]	Restrict results to these domains. Cannot combine with exclude_domains.
exclude_domains	list[str]	Exclude results from these domains. Cannot combine with include_domains.
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 results.
ignore_invalid_urls	bool	Ignore invalid URLs in results.
timeout	int	Timeout in milliseconds. Default: 300000.
highlights	bool	Generate query-relevant highlights. Default: True.
scrape_options	ScrapeOptions | dict	Scrape options applied to each result page.
enterprise	list[str]	Enterprise options: ["zdr"] or ["anon"].
threat_protection	ThreatProtectionOptions	Enterprise per-request threat protection override.
integration	str	Integration identifier for tracking.

Returns: SearchData with optional .web, .news, and .images attributes.

Scrape

Why use it

Scrape a single URL and get its content as markdown, HTML, structured JSON, screenshots, or other formats.

Preferred SDK method

app.scrape(url, **kwargs)

Example

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

print(doc.markdown)

Parameters

Parameter	Type	Description
url	str	Required. The URL to scrape.
formats	list	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "changeTracking", "branding", "product", "menu", "audio", "video", or dicts like {"type": "question", "question": "..."} and {"type": "highlights", "query": "..."}.
only_main_content	bool	Extract only the main content, excluding headers/navs/footers.
include_tags	list[str]	HTML tags to include in output.
exclude_tags	list[str]	HTML tags to exclude from output.
timeout	int	Timeout in milliseconds (1000–300000).
wait_for	int	Delay in ms before fetching content.
mobile	bool	Emulate a mobile device.
headers	dict[str, str]	Custom HTTP headers to send with the request.
actions	list	Browser actions before scraping: wait, click, write, press, scroll, screenshot, scrape, executeJavascript, pdf.
parsers	list	Parser configs. Include "pdf" to extract PDF content to markdown.
location	Location	Geo-location with country and languages fields.
skip_tls_verification	bool	Skip TLS certificate verification.
remove_base64_images	bool	Remove base64 images from output.
fast_mode	bool	Enable fast mode (less accuracy).
block_ads	bool	Block ads and cookie popups.
proxy	str	Proxy tier: "basic", "stealth", "enhanced", "auto".
max_age	int	Use cached result if younger than this (ms).
store_in_cache	bool	Store result in Firecrawl cache.
lockdown	bool	Serve from cache only; never makes outbound request.
redact_pii	bool	Redact PII from returned content.
audit_metadata	AuditMetadata	User attribution for SIEM logging (username field).
profile	dict	Persistent browser profile for session continuity.
integration	str	Integration identifier.
threat_protection	ThreatProtectionOptions	Enterprise per-request threat protection override.

Returns: Document with attributes like markdown, html, raw_html, links, images, screenshot, metadata, etc.

Interact

Why use it

Execute code or send a natural-language prompt in the browser session of a previous scrape job. Use this for clicking buttons, filling forms, navigating multi-step flows, or running arbitrary JavaScript/Python/Bash in the browser sandbox.

Preferred SDK method

app.interact(job_id, code=None, prompt=None, **kwargs)

Example

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

result = app.interact(
    job_id,
    code="document.querySelector('button.load-more').click();",
    language="node",
    timeout=30,
)

print(result.stdout)

Parameters

Parameter	Type	Description
job_id	str	Required. The scrape job ID.
code	str	Code to execute. One of code or prompt is required.
prompt	str	Natural-language instruction for the AI browser agent. One of code or prompt is required.
language	"python" | "node" | "bash"	Execution language. Default: "node".
timeout	int	Execution timeout in seconds (1–300).

Returns: BrowserExecuteResponse with success, stdout, stderr, result, exit_code, killed, error.

Stop the session:

app.stop_interaction(job_id)

Notes

• All parameter names use snake_case (e.g. only_main_content, skip_tls_verification, scrape_options).
• include_domains and exclude_domains on search are mutually exclusive.
• The SearchData return type has .web, .news, and .images attributes. Accessing .data raises an AttributeError with migration guidance.
• An async client is available: from firecrawl import AsyncFirecrawl.
• Deprecated aliases (use the preferred names instead):
  • scrape_url() → scrape()
  • scrape_execute() → interact()
  • stop_interactive_browser() / delete_scrape_browser() → stop_interaction()
  • FirecrawlApp → Firecrawl

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