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

Install

pip install firecrawl

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()

When To Use What

• search — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
• scrape — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
• interact — Use when a page needs browser automation after scraping — clicks, form fills, or post-scrape dynamic content extraction.

Search

Why use it

Search the web for a query and get results with titles, URLs, descriptions, and optionally full page content. Supports filtering by domain, time range, category, and source type.

Preferred SDK method

app.search(query, **kwargs)

Example

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

for result in results.web:
    print(result.title, result.url)
    print(result.markdown)  # available when scrape_options is set

Parameters

Parameter	Type	Description
query	str	The search query (max 500 chars). Required.
limit	int	Max results to return per source type. Default: 5 (SDK), 10 (API). Range: 1–100.
sources	list[str | Source]	Source types: "web", "news", "images", "alexandria". Default: ["web"].
categories	list[str | Category]	Filter by category: "github", "research", "pdf", "developer", "gov".
include_domains	list[str]	Restrict results to these domains (hostnames only). Cannot combine with exclude_domains.
exclude_domains	list[str]	Exclude results from these domains. Cannot combine with include_domains.
tbs	str	Time-based filter. Predefined: qdr:h (hour), qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year). Custom: cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY. Sort by date: sbd:1. Combinable.
location	str	Location for search results (city/region name).
country	str	ISO 3166-1 alpha-2 country code.
highlights	bool	Return query-relevant highlights.
timeout	int	Timeout in milliseconds. Default: 300000.
ignore_invalid_urls	bool	Skip invalid URLs instead of failing.
scrape_options	ScrapeOptions | dict	Apply scrape options to each search result page to get full content.
domain_tools	bool	Include Alexandria tool contracts matched to result domains.
tool_detail	"compact" | "summary" | "full"	Detail level for returned tool contracts. Default: "compact".
integration	str	Integration identifier.
enterprise	list[str]	Enterprise options: "default", "anon", "zdr".

Scrape

Why use it

Scrape a URL and get its content in your chosen format — markdown, HTML, JSON (with schema-based extraction), screenshots, and more. Supports browser actions, caching, proxies, and PDF parsing.

Preferred SDK method

app.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	The URL to scrape. Required.
formats	list[FormatOption]	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "json", "summary", "audio", "video", "changeTracking", "branding", "product", "menu", "question", "highlights". Default: ["markdown"]. Some accept config dicts.
only_main_content	bool	Strip headers, navs, footers. Deterministic HTML filter, no LLM. Default: true (API).
only_clean_content	bool	Additional LLM-based boilerplate removal pass. Default: false.
include_tags	list[str]	Only include content from these HTML tags.
exclude_tags	list[str]	Exclude content from these HTML tags.
headers	dict[str, str]	Custom HTTP headers (cookies, user-agent, etc.).
wait_for	int	Extra delay in ms before fetching content, on top of smart-wait. Default: 0.
timeout	int	Request timeout in ms. Min: 1000, default: 60000, max: 300000.
mobile	bool	Emulate a mobile device. Default: false.
max_age	int	Use cached result if younger than this (ms). Default: 172800000 (2 days). Set 0 to bypass cache.
min_age	int	Cache-only mode. Returns cached data if it exists, 404 otherwise. Set 1 to accept any cached data.
store_in_cache	bool	Cache this scrape result.
actions	list[Action]	Browser actions to perform before scraping (wait, click, type, scroll, screenshot, etc.).
location	Location	Geolocation: Location(country="US", languages=["en"]).
parsers	list[str | PDFParser]	File parsers. Default: ["pdf"]. PDF parser supports mode ("fast", "auto", "ocr"), max_pages, pages, blocks, page_markers.
proxy	str	Proxy type: "basic", "stealth", "enhanced", "auto".
skip_tls_verification	bool	Skip TLS cert verification. Default: true (API).
remove_base64_images	bool	Strip base64 images from output.
block_ads	bool	Block ads and cookie popups.
fast_mode	bool	Enable fast scraping mode.
lockdown	bool	Serve only cached results.
check_prompt_injection	bool	Scan content for prompt injection (adds 4 credits).
redact_pii	bool | RedactPIIOptions	Redact personally identifiable information.
profile	dict	Persistent browser profile: {"name": "my-profile", "save_changes": True}.
domain_tools	bool	Return Alexandria tool contracts matched to the scraped domain.
tool_detail	"compact" | "summary" | "full"	Detail level for tool contracts.
integration	str	Integration identifier.

Interact

Why use it

After scraping a page, interact with it in a live browser session — execute code or natural-language prompts to click buttons, fill forms, navigate, and extract dynamic content.

Preferred SDK method

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

Example

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

response = app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max")
print(response.output)

result = app.interact(scrape_id, code="document.title", language="node")
print(result.result)

app.stop_interaction(scrape_id)

Parameters

Parameter	Type	Description
job_id	str	The scrape job ID from a previous scrape’s metadata["scrapeId"]. Required.
code	str	Code to execute in the browser sandbox. Provide code or prompt. Max 100,000 chars.
prompt	str	Natural-language instruction for the browser agent. Provide code or prompt.
language	"python" | "node" | "bash"	Language for code execution. Default: "node".
timeout	int	Execution timeout in seconds. Min: 1, default: 30 (API), max: 300.
origin	str	Origin label for telemetry.

Stopping an interaction

Call app.stop_interaction(job_id) to close the browser session and stop billing.

Notes

• Deprecated aliases: scrape_url → scrape, scrape_execute → interact, stop_interactive_browser / delete_scrape_browser → stop_interaction. Always use the preferred names.
• Backward-compat class names: FirecrawlApp is an alias for Firecrawl. Use Firecrawl.
• Parameter naming: All parameters use snake_case. The SDK automatically converts to camelCase for the API.
• Package name: firecrawl (PyPI).
• Async support: Use AsyncFirecrawl for async/await patterns.
• Base URL: Defaults to https://api.firecrawl.dev. Override with api_url in the constructor for self-hosted instances.

Source Of Truth

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