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

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

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

​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

Notes

Source Of Truth