Python Agent Quickstart

Canonical Firecrawl Python quickstart for agents. Generated from SDK source (firecrawl-py v4.22.1) and the v2 OpenAPI spec.

Install

pip install firecrawl-py

Authenticate

import os
from firecrawl import Firecrawl

client = Firecrawl(api_key=os.environ.get("FIRECRAWL_API_KEY"))
# client = Firecrawl(api_key="fc-...", api_url="https://api.firecrawl.dev")

An async client is available as AsyncFirecrawl.

When To Use What

search: use when you start with a query and need discovery.
scrape: use when you already have a URL and want page content.
interact: use when the page needs clicks, forms, or post-scrape browser actions. Requires a scrape_id from a prior scrape.

Search

Why use it

Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with site: in the query string.

Preferred SDK method

client.search(query, **options) → SearchData

Example

results = client.search(
    "site:docs.firecrawl.dev webhook retries",
    sources=["web", "news"],
    limit=10,
    scrape_options=ScrapeOptions(
        formats=["markdown"],
        only_main_content=True,
    ),
)

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

Results are grouped by source: results.web, results.news, results.images. Do not access results.data.

Parameters

Parameter	Type	Description
`query`	`str`	Search query. Use `site:example.com` to scope to a domain.
`sources`	`list[str \| Source]`	Which result sources to include: `"web"`, `"news"`, `"images"`.
`categories`	`list[str \| Category]`	Filter results: `"github"`, `"developer"`, `"research"`, `"pdf"`.
`include_domains`	`list[str]`	Restrict results to these domains. Mutually exclusive with `exclude_domains`.
`exclude_domains`	`list[str]`	Exclude results from these domains. Mutually exclusive with `include_domains`.
`limit`	`int`	Max results. Defaults to `5`.
`tbs`	`str`	Time-based filter (e.g. `qdr:d`, `qdr:w`).
`location`	`str`	Location string for localized results.
`ignore_invalid_urls`	`bool`	Drop URLs that cannot be scraped.
`timeout`	`int`	Request timeout in milliseconds. Defaults to `300000`.
`highlights`	`bool`	Generate query-relevant highlights. Defaults to `True`.
`scrape_options`	`ScrapeOptions`	Scrape each search result (see Scrape parameters).
`enterprise`	`list[str]`	Enterprise options: `["zdr"]` for Zero Data Retention, `["anon"]` for anonymized search.

Scrape

Why use it

Get structured content from a URL in one or more formats.

Preferred SDK method

client.scrape(url, **options) → Document

Example

doc = client.scrape(
    "https://example.com/pricing",
    formats=[
        "markdown",
        "links",
        {"type": "json", "prompt": "Extract plan names and prices."},
    ],
    only_main_content=True,
    wait_for=1000,
)
print(doc.markdown)

Parameters

Parameter	Type	Description
`url`	`str`	The URL to scrape.
`formats`	`list`	Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"` (or `"raw_html"`), `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"` (or `"change_tracking"`), `"attributes"`, `"branding"`, `"audio"`, `"video"`. Objects: `{"type": "json", "prompt": ..., "schema": ...}`, `{"type": "question", "question": ...}`, `{"type": "highlights", "query": ...}`, `{"type": "screenshot", "full_page": ..., "quality": ..., "viewport": ...}`, `{"type": "changeTracking", "modes": [...], "tag": ...}`, `{"type": "attributes", "selectors": [{"selector": ..., "attribute": ...}]}`.
`headers`	`dict[str, str]`	Custom HTTP headers.
`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`	Strip nav, footer, and boilerplate.
`timeout`	`int`	Timeout in milliseconds.
`wait_for`	`int`	Wait for page to render (milliseconds).
`mobile`	`bool`	Use a mobile viewport.
`parsers`	`list`	File parsers. `"pdf"` or `PDFParser(mode="fast" \| "auto" \| "ocr", max_pages=...)`.
`actions`	`list`	Pre-scrape browser actions: `WaitAction`, `ClickAction`, `WriteAction`, `PressAction`, `ScrollAction`, `ScreenshotAction`, `ScrapeAction`, `ExecuteJavascriptAction`, `PDFAction`.
`location`	`Location`	`Location(country="US", languages=["en-US"])` for geo-aware scraping.
`skip_tls_verification`	`bool`	Skip TLS verification.
`remove_base64_images`	`bool`	Drop base64 images from markdown.
`fast_mode`	`bool`	Faster scrapes with reduced fidelity.
`block_ads`	`bool`	Block ads and cookie popups.
`proxy`	`str`	Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.
`max_age`	`int`	Accept cached data up to this age (milliseconds). Set to `0` to bypass index reuse.
`store_in_cache`	`bool`	Cache the result.
`lockdown`	`bool`	Serve only previously cached results; never make outbound requests.
`profile`	`dict`	Persistent browser profile: `{"name": "...", "saveChanges": True}`.
`audit_metadata`	`AuditMetadata`	User attribution for SIEM logging. Has field `username`.

Interact

Why use it

Control the browser session tied to a scrape job. Use for clicks, form fills, code execution, or natural-language browser instructions. Requires a scrape_id from a prior scrape response.

Preferred SDK method

client.interact(job_id, code=None, *, prompt=None, language="node", timeout=None) prompt is keyword-only. At least one of code or prompt must be provided.

Example

doc = client.scrape("https://example.com", formats=["markdown"])
job_id = doc.metadata.scrape_id if doc.metadata else None
if not job_id:
    raise RuntimeError("Missing scrape_id")

# Natural-language interaction
result = client.interact(job_id, prompt="Click the pricing tab and summarize the plans.")

# Code-based interaction
result = client.interact(
    job_id,
    code="print(await page.title())",
    language="python",
    timeout=60,
)

# Stop the session when done
client.stop_interaction(job_id)

Parameters

Parameter	Type	Description
`job_id`	`str`	Scrape job ID from `document.metadata.scrape_id`.
`code`	`str`	Code to execute in the browser session. At least one of `code` or `prompt` required.
`prompt`	`str`	Natural-language instruction for the browser agent (keyword-only). At least one of `code` or `prompt` required.
`language`	`"python" \| "node" \| "bash"`	Runtime for code execution. Defaults to `"node"`.
`timeout`	`int`	Execution timeout in seconds.

client.stop_interaction(job_id) ends the browser session. Returns BrowserDeleteResponse with success, optional session_duration_ms, credits_billed, error.

Notes

Deprecated aliases: scrape_execute → interact; stop_interactive_browser and delete_scrape_browser → stop_interaction; scrape_url → scrape.
The top-level Firecrawl client exposes v2 methods directly; v1 remains under client.v1.
FirecrawlApp is a deprecated alias for Firecrawl; AsyncFirecrawlApp is a deprecated alias for AsyncFirecrawl.
Format strings accept both camelCase ("rawHtml") and snake_case ("raw_html").
"json" as a plain string in formats is allowed in Python (unlike Node.js), but an object form {"type": "json", "prompt": ...} is preferred for extraction.

Source Of Truth

firecrawl/apps/python-sdk/pyproject.toml
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

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

​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

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