Firecrawl Python Agent Quickstart

This is the canonical quickstart for external agents integrating with Firecrawl using the official Python SDK. Generated from SDK source and OpenAPI spec.

Install

pip install firecrawl-py

Authenticate

from firecrawl import Firecrawl

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

Constructor parameters:

Parameter	Type	Default	Description
`api_key`	`str`	`FIRECRAWL_API_KEY` env var	API key. Omit for keyless free tier (rate-limited per IP).
`api_url`	`str`	`"https://api.firecrawl.dev"`	Base URL.
`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.

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

When To Use What

search — Use when you start with a query and need to discover relevant pages. Returns search results grouped by source type, optionally with scraped content.
scrape — Use when you already have a URL and want its content. Returns markdown, HTML, structured data, screenshots, or other formats.
interact — Use when the page needs post-scrape browser actions like clicking, filling forms, or executing code in the browser sandbox.

Search

Why use it

Search the web and optionally scrape each result in one call. Start here when you have a question or topic but not a specific URL.

Preferred SDK method

client.search(query, **kwargs)

Example

results = client.search(
    "firecrawl web scraping API",
    limit=5,
    scrape_options=ScrapeOptions(formats=["markdown"]),
)

for item in results.web or []:
    print(item.url, item.markdown[:200] if item.markdown else "")

Parameters

All parameters are keyword-only and optional unless noted.

Parameter	Type	Description
`query`	`str`	Required (positional). The search query.
`sources`	`list[str \| Source]`	Source types to search (e.g. `"web"`, `"news"`, `"images"`).
`categories`	`list[str \| Category]`	Filter by category (e.g. `"github"`, `"research"`, `"pdf"`, `"developer"`).
`include_domains`	`list[str]`	Restrict results to these domains. Mutually exclusive with `exclude_domains`.
`exclude_domains`	`list[str]`	Exclude results from these domains.
`limit`	`int`	Max results to return.
`tbs`	`str`	Time-based search filter (e.g. `"qdr:d"` for past day, `"qdr:w"` for past week).
`location`	`str`	Geographic location for results.
`ignore_invalid_urls`	`bool`	Exclude URLs invalid for other Firecrawl endpoints.
`timeout`	`int`	Timeout in milliseconds.
`highlights`	`bool`	Generate query-relevant highlights.
`scrape_options`	`ScrapeOptions`	Options applied when scraping each result. See Scrape parameters.
`integration`	`str`	Integration identifier.
`enterprise`	`list[str]`	Enterprise options (e.g. `"anon"`, `"zdr"`).
`threat_protection`	`ThreatProtectionOptions`	Per-request threat protection override.

Scrape

Why use it

Fetch and extract content from a single URL. Use when you have a specific page to read.

Preferred SDK method

client.scrape(url, **kwargs)

Example

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

print(doc.markdown)
print(doc.links)

Parameters

All parameters are keyword-only and optional unless noted.

Parameter	Type	Description
`url`	`str`	Required (positional). The URL to scrape.
`formats`	`list[FormatOption]`	Output formats. String values: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Object variants also supported for `json`, `screenshot`, `changeTracking`, `attributes`, `question`, `highlights`.
`headers`	`dict[str, str]`	Custom HTTP headers to send with the request.
`include_tags`	`list[str]`	HTML tags to include exclusively.
`exclude_tags`	`list[str]`	HTML tags to exclude.
`only_main_content`	`bool`	Only return main content, excluding navbars/footers.
`timeout`	`int`	Timeout in milliseconds.
`wait_for`	`int`	Delay in ms before fetching content.
`mobile`	`bool`	Emulate a mobile device.
`parsers`	`list[str \| PDFParser]`	File processing parsers. PDF modes: `"fast"`, `"auto"`, `"ocr"`.
`actions`	`list[Action]`	Browser actions to perform before scraping. Types: `WaitAction`, `ScreenshotAction`, `ClickAction`, `WriteAction`, `PressAction`, `ScrollAction`, `ScrapeAction`, `ExecuteJavascriptAction`, `PDFAction`.
`location`	`Location`	Geolocation config 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`	Faster scraping with reduced accuracy.
`use_mock`	`str`	Use a mock response.
`block_ads`	`bool`	Block ads and cookie popups.
`proxy`	`str`	Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.
`max_age`	`int`	Use cached result if younger than this (ms).
`store_in_cache`	`bool`	Whether to cache the result.
`lockdown`	`bool`	Serve only cached results. No outbound request.
`threat_protection`	`ThreatProtectionOptions`	Per-request threat protection override.
`profile`	`dict`	Persistent browser storage profile with `name` and optional `save_changes`.
`audit_metadata`	`AuditMetadata`	User attribution for SIEM logging with `username` field.
`integration`	`str`	Integration identifier.

Interact

Why use it

Execute code or natural-language prompts in the browser sandbox associated with a scrape job. Use after a scrape to click buttons, fill forms, navigate, or extract additional data.

Preferred SDK method

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

Example

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

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

print(result.stdout)

Parameters

Parameter	Type	Default	Description
`job_id`	`str`	—	Required (positional). The scrape job ID from a prior scrape.
`code`	`str`	`None`	Code to execute in the browser sandbox. Required if `prompt` is not provided.
`prompt`	`str`	`None`	Natural-language instruction for the browser agent. Required if `code` is not provided.
`language`	`str`	`"node"`	Runtime language: `"python"`, `"node"`, or `"bash"`.
`timeout`	`int`	`None`	Execution timeout in seconds (1-300).
`origin`	`str`	`None`	Request origin tag.

client.stop_interaction(job_id)

Stops the interactive browser session and returns billing info.

Notes

Naming style: All parameters use snake_case.
Deprecated aliases:
- scrape_url() → use scrape() instead.
- scrape_execute() → use interact() instead.
- stop_interactive_browser() and delete_scrape_browser() → use stop_interaction() instead.
- FirecrawlApp → use Firecrawl instead (alias still works).
Async client: Use AsyncFirecrawl (aliased as AsyncFirecrawlApp) for async/await usage with the same method signatures.
ScrapeOptions model: The ScrapeOptions Pydantic model also includes min_age and redact_pii fields which are available when passing scrape_options to search() but are not direct kwargs on scrape().

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

Getting Started

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agent Quickstarts

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

​Related method

​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

Related method

Notes

Source Of Truth