Firecrawl Python Agent Quickstart

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

Install

pip install firecrawl-py

Authenticate

from firecrawl import Firecrawl

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

Or use the FIRECRAWL_API_KEY environment variable:

firecrawl = Firecrawl()

Constructor parameters:

Parameter	Type	Default	Description
`api_key`	`str`	`None`	API key. Falls back to `FIRECRAWL_API_KEY` env var, then keyless free tier (rate-limited per IP).
`api_url`	`str`	`"https://api.firecrawl.dev"`	Base API URL.
`timeout`	`float`	`None`	Default request timeout in seconds.
`max_retries`	`int`	`3`	Max retries for failed requests.
`backoff_factor`	`float`	`0.5`	Exponential backoff factor for retries.

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

When To Use What

search: Start with a query and discover relevant pages. Returns URLs, titles, descriptions, and optionally scraped content.
scrape: You already have a URL and want structured page content — markdown, HTML, screenshots, JSON extraction, etc.
interact: The page needs post-scrape browser actions — clicking, typing, executing code, or natural-language browser instructions.

Search

Why use it

Discover web pages matching a query. Optionally scrape each result for full content in one call.

Preferred SDK method

firecrawl.search(query, **kwargs)

Example

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")
results = firecrawl.search("firecrawl web scraping", limit=5)

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

Parameters

Parameter	Type	Description
`query`	`str`	Search query. Required (first positional argument).
`limit`	`int`	Max number of results per source type. Default `5`.
`sources`	`list[str \| Source]`	Result sources: `"web"`, `"news"`, `"images"`. Defaults to `["web"]`.
`categories`	`list[str \| Category]`	Narrow results: `"github"`, `"research"`, `"pdf"`, `"developer"`.
`include_domains`	`list[str]`	Restrict to these domains. Mutually exclusive with `exclude_domains`.
`exclude_domains`	`list[str]`	Exclude these domains. Mutually exclusive with `include_domains`.
`tbs`	`str`	Time-based filter: `"qdr:h"` (hour), `"qdr:d"` (day), `"qdr:w"` (week), `"qdr:m"` (month), `"qdr:y"` (year), or custom date ranges.
`location`	`str`	Location string for geo-targeted results (e.g. `"San Francisco,California,United States"`).
`ignore_invalid_urls`	`bool`	Skip invalid URLs. Useful when piping results to other Firecrawl endpoints.
`timeout`	`int`	Timeout in milliseconds. Default `300000`.
`highlights`	`bool`	Generate query-relevant highlights. Defaults to `true` server-side. Set `False` for raw descriptions.
`scrape_options`	`ScrapeOptions`	Scrape each result page. Same parameters as the scrape endpoint below.
`enterprise`	`list[str]`	Enterprise options: `["zdr"]` for zero data retention, `["anon"]` for anonymized search.
`threat_protection`	`ThreatProtectionOptions`	Per-request threat protection override.
`integration`	`str`	Integration identifier for attribution.

Results are grouped by source: results.web, results.news, results.images, results.developer.

Scrape

Why use it

Extract structured content from a single URL — markdown, HTML, screenshots, JSON extraction, audio, video, and more.

Preferred SDK method

firecrawl.scrape(url, **kwargs)

Example

result = firecrawl.scrape("https://example.com", formats=["markdown", "links"])
print(result.markdown)
print(result.links)

Parameters

Parameter	Type	Description
`url`	`str`	URL to scrape. Required (first positional argument).
`formats`	`list[FormatOption]`	Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"` (or `"raw_html"`), `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"` (or `"change_tracking"`), `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Or format objects like `JsonFormat`, `QuestionFormat`, `HighlightsFormat`.
`headers`	`dict[str, str]`	Custom HTTP headers. Use for cookies, auth tokens, user-agent.
`include_tags`	`list[str]`	Only include content from these HTML tags.
`exclude_tags`	`list[str]`	Exclude content from these HTML tags.
`only_main_content`	`bool`	Extract only main content, excluding headers/navs/footers.
`timeout`	`int`	Timeout in milliseconds. Min `1000`, max `300000`. Default `60000`.
`wait_for`	`int`	Additional wait in milliseconds before scraping. Use for JS-rendered content.
`mobile`	`bool`	Emulate a mobile device.
`parsers`	`list`	Parser config: `["pdf"]` or `[PDFParser(mode="fast" \| "auto" \| "ocr", max_pages=N)]`.
`actions`	`list`	Browser actions before scraping: `WaitAction`, `ScreenshotAction`, `ClickAction`, `WriteAction`, `PressAction`, `ScrollAction`, `ScrapeAction`, `ExecuteJavascriptAction`, `PDFAction`.
`location`	`Location`	Location settings: `Location(country="US", languages=["en-US"])`.
`skip_tls_verification`	`bool`	Skip TLS certificate verification.
`remove_base64_images`	`bool`	Remove base64 images from markdown output.
`fast_mode`	`bool`	Faster scrape with reduced accuracy.
`block_ads`	`bool`	Block ads and cookie popups.
`proxy`	`str`	Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.
`max_age`	`int`	Max age in ms of cached content. `0` bypasses cache. Default `172800000` (2 days).
`store_in_cache`	`bool`	Store result in Firecrawl cache.
`lockdown`	`bool`	Serve only cached results, never make outbound requests.
`threat_protection`	`ThreatProtectionOptions`	Per-request threat protection override.
`profile`	`dict`	Persistent browser profile: `{"name": "my-profile", "saveChanges": True}`.
`audit_metadata`	`AuditMetadata`	User attribution for SIEM logging: `AuditMetadata(username="user")`.
`integration`	`str`	Integration identifier.

Interact

Why use it

Continue interacting with a live browser session after scraping. Execute code or send natural-language prompts to control the page — click buttons, fill forms, navigate, and extract dynamic content.

Preferred SDK method

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

Example

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

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

firecrawl.stop_interaction(scrape_id)

Parameters

Parameter	Type	Description
`job_id`	`str`	Scrape job ID. Required (first positional argument). Obtained from `result.metadata.scrape_id` of a previous scrape.
`code`	`str`	Code to execute in the browser session. One of `code` or `prompt` is required. Second positional argument.
`prompt`	`str`	Natural-language instruction for the browser agent. One of `code` or `prompt` is required. Keyword-only.
`language`	`"python" \| "node" \| "bash"`	Language for code execution. Defaults to `"node"`. Keyword-only.
`timeout`	`int`	Execution timeout in seconds (1-300). Keyword-only.
`origin`	`str`	Origin identifier. Keyword-only.

Call firecrawl.stop_interaction(job_id) to end the browser session when done.

Notes

snake_case parameters: All parameters use snake_case (e.g. only_main_content, include_tags, scrape_options). The SDK converts to camelCase for the API.
Format string aliases: Both camelCase and snake_case format strings are accepted (e.g. "rawHtml" and "raw_html" both work).
SearchData structure: Access results via results.web, results.news, results.images, or results.developer. Accessing results.data raises AttributeError.
Pydantic models: Return types (Document, SearchData, BrowserExecuteResponse) are Pydantic models with attribute-style access.
Deprecated aliases: FirecrawlApp -> Firecrawl, scrape_execute -> interact, stop_interactive_browser / delete_scrape_browser -> stop_interaction, scrape_url -> scrape.

Source Of Truth

SDK source: firecrawl/apps/python-sdk/firecrawl/v2/client.py, firecrawl/apps/python-sdk/firecrawl/v2/types.py
OpenAPI spec: firecrawl-docs/api-reference/v2-openapi.json

Getting Started

Agent Quickstarts

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Cookbooks

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