Firecrawl Python Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (firecrawl-py) and the OpenAPI spec. Use this file to get an agent calling Firecrawl correctly in one pass.

Install

pip install firecrawl-py

Authenticate

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")
# or read from env automatically:
app = Firecrawl()  # uses FIRECRAWL_API_KEY env var

Constructor parameters:

app = Firecrawl(
    api_key="fc-...",                        # optional; falls back to FIRECRAWL_API_KEY
    api_url="https://api.firecrawl.dev",     # optional
    timeout=None,                            # optional; default HTTP request timeout (seconds)
    max_retries=3,                           # optional
    backoff_factor=0.5,                      # optional
)

An async client is also available: from firecrawl import AsyncFirecrawl. No API key is required for scrape, search, and interact — they fall back to a keyless free tier (rate-limited per IP).

When To Use What

search: Start with a text query and need to discover relevant URLs and content across the web.
scrape: Already have a URL and want page content (markdown, HTML, structured JSON, screenshots, etc.).
interact: The page needs clicks, form fills, or post-scrape browser actions — run code or a prompt against the live browser session.

Search

Why use it

Search the web and optionally scrape each result. Returns categorized results (web, news, images) with optional content scraping.

Preferred SDK method

app.search(query, **options)

Example

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

for item in results.web or []:
    print(item.url, item.title)

Parameters

Parameter	Type	Description
`query`	`str`	Required. The search query.
`limit`	`int`	Max number of results. Default: `5`.
`sources`	`list[str]`	Which result sources: `"web"`, `"news"`, `"images"`.
`categories`	`list[str]`	Narrow web results: `"github"`, `"research"`, `"pdf"`, `"developer"`.
`include_domains`	`list[str]`	Only include results from these domains. Mutually exclusive with `exclude_domains`.
`exclude_domains`	`list[str]`	Exclude results from these domains.
`tbs`	`str`	Time-based search filter (e.g. `"qdr:d"` for past day).
`location`	`str`	Location string for geo-targeting. Note: plain string, not a `Location` object.
`country`	`str`	ISO country code for geo-targeting.
`ignore_invalid_urls`	`bool`	Exclude URLs invalid for other Firecrawl endpoints.
`timeout`	`int`	Timeout in milliseconds. Default: `300000`.
`highlights`	`bool`	Generate query-relevant highlights. Default: `True`.
`scrape_options`	`ScrapeOptions`	Scrape options applied to each result page.
`enterprise`	`list[str]`	Enterprise options (e.g. `["zdr"]` or `["anon"]`).
`threat_protection`	`ThreatProtectionOptions`	Enterprise per-request threat config.
`integration`	`str`	Integration identifier.

Return type: SearchData with properties .web, .news, .images. Accessing .data raises an AttributeError with guidance.

Scrape

Why use it

Fetch a single URL and extract content in various formats: markdown, HTML, structured JSON, screenshots, audio, video, and more. Handles JavaScript rendering, ad blocking, proxies, and caching.

Preferred SDK method

app.scrape(url, **options)

Example

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

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

Parameters

Parameter	Type	Description
`url`	`str`	Required. The URL to scrape.
`formats`	`list`	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"attributes"`, `"audio"`, `"video"`, `"branding"`, `"product"`, `"menu"`, `"changeTracking"`. Also accepts format config dicts.
`headers`	`dict[str, str]`	Custom HTTP headers.
`include_tags`	`list[str]`	HTML tags to include in extraction.
`exclude_tags`	`list[str]`	HTML tags to exclude from extraction.
`only_main_content`	`bool`	Strip boilerplate (nav, footer, etc.).
`timeout`	`int`	Server-side timeout in milliseconds.
`wait_for`	`int`	Wait before scraping in milliseconds (for JS rendering).
`mobile`	`bool`	Emulate a mobile viewport.
`parsers`	`list`	Parser config (e.g. PDF mode, max_pages, blocks).
`actions`	`list`	Browser actions: wait, click, write, press, scroll, scrape, executeJavascript, screenshot, pdf.
`location`	`Location`	`Location(country=..., languages=[...])` for geo-targeting.
`skip_tls_verification`	`bool`	Skip TLS certificate checks.
`remove_base64_images`	`bool`	Strip base64-encoded images from output.
`fast_mode`	`bool`	Enable fast mode (less rendering, faster response).
`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.
`store_in_cache`	`bool`	Store the result in Firecrawl’s cache.
`lockdown`	`bool`	Only serve cached results; never make an outbound request.
`threat_protection`	`ThreatProtectionOptions`	Enterprise per-request threat config.
`audit_metadata`	`AuditMetadata`	SIEM logging attribution (`username` field).
`profile`	`dict`	Persistent browser profile across sessions.
`integration`	`str`	Integration identifier.
`auto_resume`	`bool`	SDK-only. Auto-resume large docs that outlive the request window.

Interact

Why use it

Execute code or a natural-language prompt against the live browser session from a previous scrape. Use it to click buttons, fill forms, navigate, or extract dynamic content that only appears after user interaction.

Preferred SDK method

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

Example

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

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

print(result.output)

# When done, stop the session:
app.stop_interaction(job_id)

Parameters

Parameter	Type	Description
`job_id`	`str`	Required. The scrape job ID from a previous `scrape` call.
`code`	`str`	Code to execute in the browser sandbox. At least one of `code` or `prompt` is required.
`prompt`	`str`	Natural-language prompt to execute. At least one of `code` or `prompt` is required.
`language`	`"python" \| "node" \| "bash"`	Language of the code. Default: `"node"`.
`timeout`	`int`	Execution timeout in seconds (1–300).

Stop the session when done:

app.stop_interaction(job_id)

Notes

All parameter names use snake_case (e.g. only_main_content, skip_tls_verification).
SearchData uses .web, .news, .images — accessing .data raises AttributeError with migration guidance.
Deprecated aliases (use the preferred names above):
- scrape_url → scrape
- scrape_execute → interact
- delete_scrape_browser / stop_interactive_browser → stop_interaction
- FirecrawlApp → Firecrawl
- AsyncFirecrawlApp → AsyncFirecrawl

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

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