Firecrawl Python Agent Quickstart

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

Install

pip install firecrawl-py

Authenticate

from firecrawl import Firecrawl

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

The API key can also be set via the FIRECRAWL_API_KEY environment variable. Omitting the key uses the keyless free tier (rate-limited per IP). Client options:

Option	Type	Default	Description
`api_key`	`str`	`FIRECRAWL_API_KEY` env var	API key for authentication
`api_url`	`str`	`"https://api.firecrawl.dev"`	Base URL for the API
`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

When To Use What

search: Use when you start with a query and need to discover relevant pages. Returns ranked results with optional scraping of each result.
scrape: Use when you already have a URL and want its content in markdown, HTML, JSON, or other formats.
interact: Use when a page needs post-scrape browser actions — clicking, filling forms, running code, or prompting an AI agent in the browser.

Search

Why use it

Search the web for a query and get back ranked results. Optionally scrape each result page inline by passing scrape_options.

Preferred SDK method

app.search(query, **kwargs)

Example

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

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

Parameters

Parameter	Type	Description
`query`	`str`	Required. The search query (max 500 chars).
`limit`	`int`	Max results to return. Default: `5`.
`sources`	`list`	Which result sources to include: `"web"`, `"news"`, `"images"`.
`categories`	`list`	Filter results by category: `"github"`, `"research"`, `"pdf"`, `"developer"`.
`include_domains`	`list[str]`	Restrict results to these domains. Cannot combine with `exclude_domains`.
`exclude_domains`	`list[str]`	Exclude results from these domains. Cannot combine with `include_domains`.
`tbs`	`str`	Time-based search filter (e.g. `"qdr:d"` for past day, `"qdr:w"` for past week).
`location`	`str`	Location string for geo-targeted results.
`ignore_invalid_urls`	`bool`	Ignore invalid URLs in results.
`timeout`	`int`	Timeout in milliseconds. Default: `300000`.
`highlights`	`bool`	Generate query-relevant highlights. Default: `True`.
`scrape_options`	`ScrapeOptions \| dict`	Scrape options applied to each result page.
`enterprise`	`list[str]`	Enterprise options: `["zdr"]` or `["anon"]`.
`threat_protection`	`ThreatProtectionOptions`	Enterprise per-request threat protection override.
`integration`	`str`	Integration identifier for tracking.

Returns: SearchData with optional .web, .news, and .images attributes.

Scrape

Why use it

Scrape a single URL and get its content as markdown, HTML, structured JSON, screenshots, or other formats.

Preferred SDK method

app.scrape(url, **kwargs)

Example

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

print(doc.markdown)

Parameters

Parameter	Type	Description
`url`	`str`	Required. The URL to scrape.
`formats`	`list`	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or dicts like `{"type": "question", "question": "..."}` and `{"type": "highlights", "query": "..."}`.
`only_main_content`	`bool`	Extract only the main content, excluding headers/navs/footers.
`include_tags`	`list[str]`	HTML tags to include in output.
`exclude_tags`	`list[str]`	HTML tags to exclude from output.
`timeout`	`int`	Timeout in milliseconds (1000–300000).
`wait_for`	`int`	Delay in ms before fetching content.
`mobile`	`bool`	Emulate a mobile device.
`headers`	`dict[str, str]`	Custom HTTP headers to send with the request.
`actions`	`list`	Browser actions before scraping: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`.
`parsers`	`list`	Parser configs. Include `"pdf"` to extract PDF content to markdown.
`location`	`Location`	Geo-location 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`	Enable fast mode (less accuracy).
`block_ads`	`bool`	Block ads and cookie popups.
`proxy`	`str`	Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.
`max_age`	`int`	Use cached result if younger than this (ms).
`store_in_cache`	`bool`	Store result in Firecrawl cache.
`lockdown`	`bool`	Serve from cache only; never makes outbound request.
`redact_pii`	`bool`	Redact PII from returned content.
`audit_metadata`	`AuditMetadata`	User attribution for SIEM logging (`username` field).
`profile`	`dict`	Persistent browser profile for session continuity.
`integration`	`str`	Integration identifier.
`threat_protection`	`ThreatProtectionOptions`	Enterprise per-request threat protection override.

Returns: Document with attributes like markdown, html, raw_html, links, images, screenshot, metadata, etc.

Interact

Why use it

Execute code or send a natural-language prompt in the browser session of a previous scrape job. Use this for clicking buttons, filling forms, navigating multi-step flows, or running arbitrary JavaScript/Python/Bash in the browser sandbox.

Preferred SDK method

app.interact(job_id, code=None, prompt=None, **kwargs)

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.stdout)

Parameters

Parameter	Type	Description
`job_id`	`str`	Required. The scrape job ID.
`code`	`str`	Code to execute. One of `code` or `prompt` is required.
`prompt`	`str`	Natural-language instruction for the AI browser agent. One of `code` or `prompt` is required.
`language`	`"python" \| "node" \| "bash"`	Execution language. Default: `"node"`.
`timeout`	`int`	Execution timeout in seconds (1–300).

Returns: BrowserExecuteResponse with success, stdout, stderr, result, exit_code, killed, error. Stop the session:

app.stop_interaction(job_id)

Notes

All parameter names use snake_case (e.g. only_main_content, skip_tls_verification, scrape_options).
include_domains and exclude_domains on search are mutually exclusive.
The SearchData return type has .web, .news, and .images attributes. Accessing .data raises an AttributeError with migration guidance.
An async client is available: from firecrawl import AsyncFirecrawl.
Deprecated aliases (use the preferred names instead):
- scrape_url() → scrape()
- scrape_execute() → interact()
- stop_interactive_browser() / delete_scrape_browser() → stop_interaction()
- FirecrawlApp → Firecrawl

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

Agent Quickstarts

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