Python Agent Quickstart

Canonical Firecrawl Python quickstart for external agents using search, scrape, and interact.

Firecrawl Python Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (firecrawl-py v4.41.0) and the v2 OpenAPI spec. Method names, parameters, and types match the v2 client.

Install

pip install firecrawl-py

Requires Python >= 3.8.

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")

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:, for example site:docs.firecrawl.dev crawl webhooks.

Preferred SDK method

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

Example

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

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

Wrong turn to avoid: search() does not return { data: [...] }. Web results are in result.web, news in result.news, images in result.images.

Parameters

Parameter	Type	Description
query	str	Search query. Use site:example.com to limit to a domain.
sources	list[str]	Which source indexes to search: "web", "news", "images".
categories	list[str]	Filter by category: "developer", "research", "pdf", "github".
include_domains	list[str]	Only include these domains. Cannot combine with exclude_domains.
exclude_domains	list[str]	Exclude these domains. Cannot combine with include_domains.
limit	int	Max results. Default: 5 (SDK model default).
tbs	str	Time-based filter (e.g. qdr:d for past day, qdr:w for past week).
location	str	Localized results (plain string, not a Location object).
ignore_invalid_urls	bool	Drop URLs that cannot be scraped.
highlights	bool	Return query-relevant text highlights. Defaults to true server-side.
timeout	int	Request timeout in milliseconds. Default: 300000.
scrape_options	ScrapeOptions	Scrape each search result (see Scrape parameters).
enterprise	list[str]	Enterprise options: "zdr" (zero data retention), "anon" (anonymized).

Scrape

Why use it

Fetch structured content from a URL in one or more formats. Use when you already have the URL.

Preferred SDK method

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

Example

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

print(doc.markdown)
print(doc.json)

Parameters

Parameter	Type	Description
url	str	URL to scrape.
formats	list	Output formats (see below).
headers	dict[str, str]	Custom request headers.
include_tags	list[str]	Include only these HTML tags.
exclude_tags	list[str]	Exclude these HTML tags.
only_main_content	bool	Strip nav, footer, boilerplate.
timeout	int	Timeout in milliseconds.
wait_for	int	Wait for page to render (milliseconds).
mobile	bool	Use a mobile viewport.
parsers	list	File parsing controls (e.g. {"type": "pdf", "mode": "auto", "max_pages": 5}).
actions	list[dict]	Pre-scrape browser actions (click, wait, write, press, scroll, scrape, executeJavascript, screenshot, pdf).
location	Location	Geo/language-aware scraping. Location(country="US", languages=["en-US"]).
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	Use cached data up to this age (milliseconds).
store_in_cache	bool	Cache the result.
lockdown	bool	Serve only cached results; never make outbound request.
profile	dict	Persistent browser profile: {"name": "my-session", "saveChanges": True}.

Format options:

String formats: "markdown", "html", "rawHtml" (or "raw_html"), "links", "images", "screenshot", "summary", "changeTracking" (or "change_tracking"), "attributes", "branding", "audio", "video".

Object formats:

• {"type": "json", "prompt": "...", "schema": {...}} — at least one of prompt or schema required.
• {"type": "question", "question": "..."} — question-answer extraction.
• {"type": "highlights", "query": "..."} — relevant source-text extraction.
• {"type": "screenshot", "full_page": True, "quality": 80, "viewport": {"width": 1280, "height": 720}}
• {"type": "changeTracking", "modes": ["git-diff"], "tag": "..."} — modes required.
• {"type": "attributes", "selectors": [{"selector": "a", "attribute": "href"}]}

Interact

Why use it

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

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

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

# Clean up
client.stop_interaction(job_id)

Parameters

Parameter	Type	Description
job_id	str	Scrape job ID from document.metadata.scrape_id.
code	str	Code to run in the browser session (optional if prompt is set).
prompt	str	Natural-language instruction for the browser agent (keyword-only; optional if code is set).
language	str	Runtime: "python", "node", "bash". Default: "node".
timeout	int	Execution timeout in seconds.

At least one of code or prompt must be provided.

Stop session: client.stop_interaction(job_id) ends the browser session.

Notes

• Deprecated aliases: scrape_execute → interact; stop_interactive_browser / delete_scrape_browser → stop_interaction.
• The top-level Firecrawl client exposes v2 methods directly; v1 remains under client.v1.
• FirecrawlApp is a direct alias for Firecrawl.
• search() location is a plain str, not a Location object (unlike scrape()).
• SearchRequest model defaults: limit=5, timeout=300000.

Source Of Truth

• firecrawl/apps/python-sdk/pyproject.toml
• firecrawl/apps/python-sdk/firecrawl/__init__.py
• firecrawl/apps/python-sdk/firecrawl/v2/client.py
• firecrawl/apps/python-sdk/firecrawl/v2/types.py
• firecrawl-docs/api-reference/v2-openapi.json