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

Get Started

Core Endpoints

More

Quickstarts

Agent Quickstarts

Developer Guides

Webhooks

Use Cases

Other

Contributing

Python Agent Quickstart

Firecrawl Python Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Stopping an interaction

Notes

Source Of Truth

​Firecrawl Python Agent Quickstart

​Install

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK method

​Example

​Parameters

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Interact

​Why use it

​Preferred SDK method

​Example

​Parameters

​Stopping an interaction

​Notes

​Source Of Truth

Firecrawl Python Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Stopping an interaction

Notes

Source Of Truth