Firecrawl Python Agent Quickstart

This file is the canonical quickstart for external agents integrating Firecrawl via the Python SDK. It is 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")

The API key can also be set via the FIRECRAWL_API_KEY environment variable. If omitted, the client falls back to keyless free tier (rate-limited per IP). Constructor options: api_key (str), api_url (str, default "https://api.firecrawl.dev"), timeout (float), max_retries (int, default 3), backoff_factor (float, default 0.5). 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 URLs and their content. Returns results from web, news, and image sources.
scrape: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats.
interact: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session.

Search

Why use it

Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction.

Preferred SDK method

client.search(query, **kwargs)

Example

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

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

Parameters

Parameter	Type	Description
`query`	`str`	The search query (first argument, required).
`sources`	`list[str]`	Sources to search: `"web"`, `"news"`, `"images"`.
`categories`	`list[str]`	Filter by category: `"github"`, `"research"`, `"pdf"`, `"developer"`.
`include_domains`	`list[str]`	Restrict results to these domains. Cannot be used with `exclude_domains`.
`exclude_domains`	`list[str]`	Exclude results from these domains. Cannot be used with `include_domains`.
`limit`	`int`	Maximum number of results. Server default: `10`.
`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 search.
`ignore_invalid_urls`	`bool`	Ignore invalid URLs in results.
`timeout`	`int`	Timeout in milliseconds. Server default: `60000`.
`highlights`	`bool`	Generate query-relevant highlights. Default: `True`.
`scrape_options`	`ScrapeOptions`	Nested scrape configuration applied to each result.
`enterprise`	`list[str]`	Enterprise search options for ZDR.
`threat_protection`	`ThreatProtectionOptions`	Per-request threat protection overrides.
`integration`	`str`	Integration identifier.

Return type

SearchData with attributes: web, news, images, developer. Each is a list of result dicts or None. Access results via results.web, not results.data.

Scrape

Why use it

Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more.

Preferred SDK method

client.scrape(url, **kwargs)

Example

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

print(doc.markdown)

Parameters

Parameter	Type	Description
`url`	`str`	The URL to scrape (first argument, required).
`formats`	`list`	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or typed dicts. Server default: `["markdown"]`.
`only_main_content`	`bool`	Strip boilerplate, keep main content only. Server default: `True`.
`headers`	`dict[str, str]`	Custom HTTP headers to send with the request.
`include_tags`	`list[str]`	HTML tags to exclusively include.
`exclude_tags`	`list[str]`	HTML tags to exclude.
`timeout`	`int`	Timeout in milliseconds. Min: `1000`, max: `300000`. Server default: `60000`.
`wait_for`	`int`	Delay in milliseconds before fetching content.
`mobile`	`bool`	Emulate mobile device.
`parsers`	`list`	Parser configurations (e.g. `"pdf"` or `{"type": "pdf", "mode": "auto"}`). Server default: `["pdf"]`.
`actions`	`list[dict]`	Browser automation actions. See Actions table below.
`location`	`Location`	Location settings: `{"country": "US", "languages": ["en-US"]}`.
`skip_tls_verification`	`bool`	Skip TLS certificate verification.
`remove_base64_images`	`bool`	Remove base64 images from markdown output. Server default: `True`.
`fast_mode`	`bool`	Enable fast mode for faster scrapes.
`block_ads`	`bool`	Block advertisements and cookie popups. Server default: `True`.
`proxy`	`str`	Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. Server default: `"auto"`.
`max_age`	`int`	Use cached result if younger than this many milliseconds. Server default: `172800000` (2 days).
`store_in_cache`	`bool`	Cache the scrape result. Server default: `True`.
`lockdown`	`bool`	Only serve cached results, never make outbound requests.
`threat_protection`	`ThreatProtectionOptions`	Per-request threat protection overrides.
`audit_metadata`	`AuditMetadata`	User attribution for SIEM logging: `{"username": "..."}`.
`profile`	`dict`	Persistent browser profile: `{"name": "...", "save_changes": True}`.
`integration`	`str`	Integration identifier.
`use_mock`	`str`	Use mock data.

Actions

Type	Fields
`wait`	`{"type": "wait", "milliseconds": int}` or `{"type": "wait", "selector": str}`
`screenshot`	`{"type": "screenshot", "fullPage": bool, "quality": int}`
`click`	`{"type": "click", "selector": str}`
`write`	`{"type": "write", "text": str}`
`press`	`{"type": "press", "key": str}`
`scroll`	`{"type": "scroll", "direction": "up" \| "down", "selector": str}`
`scrape`	`{"type": "scrape"}`
`executeJavascript`	`{"type": "executeJavascript", "script": str}`
`pdf`	`{"type": "pdf", "format": str, "landscape": bool, "scale": float}`

Interact

Why use it

Execute code or send natural-language prompts in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts.

Preferred SDK method

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

Example

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

result = client.interact(job_id, code="document.title", language="node")
print(result.stdout)

client.stop_interaction(job_id)

Parameters

Parameter	Type	Description
`job_id`	`str`	The scrape job ID (first argument, required).
`code`	`str`	Code to execute in the browser sandbox (positional).
`prompt`	`str`	Natural-language instruction for the browser agent (keyword-only).
`language`	`str`	Execution language: `"python"`, `"node"`, `"bash"`. Default: `"node"`.
`timeout`	`int`	Execution timeout in seconds. Range: 1-300. Server default: `30`.
`origin`	`str`	Origin identifier for telemetry.

Either code or prompt must be provided. Use client.stop_interaction(job_id) to end the browser session.

Notes

Naming style: All parameters use snake_case.
Deprecated aliases: scrape_url() is deprecated in favor of scrape(). scrape_execute() is deprecated in favor of interact(). stop_interactive_browser() and delete_scrape_browser() are deprecated in favor of stop_interaction(). FirecrawlApp is deprecated in favor of Firecrawl.
Async support: Use AsyncFirecrawl for async/await usage with the same method signatures.
Search return type: Access results via results.web, results.news, results.images, results.developer. Accessing results.data raises AttributeError with guidance.

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

Return type

Scrape

Why use it

Preferred SDK method

Example

Parameters

Actions

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

​Return type

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Actions

​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

Return type

Scrape

Why use it

Preferred SDK method

Example

Parameters

Actions

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth