Python Agent Quickstart

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

Canonical Firecrawl Python quickstart for external agents. Aligned with firecrawl-py v4.34.0 (firecrawl/apps/python-sdk) and the v2 OpenAPI spec. Method names, parameters, and types match the v2 client in firecrawl/v2/client.py.

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

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.

Search

Why use it

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. You can 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")
for item in results.web or []:
    print(getattr(item, "url", None), getattr(item, "title", None))

Parameters

Parameter	Type	Description
query	str	The search query. Use site:example.com to limit results to a domain.
sources	list[str | Source]	Which sources to search. Values: "web", "news", "images".
categories	list[str | Category]	Filter by category. Values: "github", "research", "pdf", "developer".
include_domains	list[str]	Restrict results to these domains. Mutually exclusive with exclude_domains.
exclude_domains	list[str]	Exclude these domains. Mutually exclusive with include_domains.
limit	int	Cap results. Default: 5 in SDK model.
tbs	str	Time-based filter (e.g. qdr:d, qdr:w, sbd:1,qdr:m).
location	str	Location string for localized results.
ignore_invalid_urls	bool	Drop URLs that cannot be scraped by other endpoints.
timeout	int	Request timeout in milliseconds. Default: 300000.
highlights	bool	Generate query-relevant highlights. Defaults to true server-side.
scrape_options	ScrapeOptions	Scrape each search result (see Scrape parameters).
enterprise	list[str]	Enterprise options. "zdr" for zero data retention, "anon" for anonymized search.

Return value: SearchData with optional lists web, news, images, developer. Do not access result.data — it raises AttributeError directing you to use result.web, result.news, etc.

Scrape

Why use it

Use scrape when you already have a URL and want structured content in one or more formats.

Preferred SDK method

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

Example

doc = client.scrape("https://docs.firecrawl.dev", formats=["markdown"])
print(doc.markdown)

Parameters

Parameter	Type	Description
url	str	The URL to scrape.
formats	list[str | dict]	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": [...]}. Note: plain string "json" is rejected — use the dict form.
headers	dict[str, str]	Custom request headers.
include_tags	list[str]	Include only specific HTML tags.
exclude_tags	list[str]	Exclude specific HTML tags.
only_main_content	bool	Strip nav, footer, and other boilerplate.
timeout	int	Timeout in milliseconds.
wait_for	int	Wait for the page to render (milliseconds).
mobile	bool	Use a mobile viewport.
parsers	list[str | PDFParser]	File parsing controls. PDF modes: "fast", "auto", "ocr".
actions	list[dict]	Pre-scrape browser actions. Types: wait, screenshot, click, write, press, scroll, scrape, executeJavascript, pdf.
location	Location	Geo or language-aware scraping. Fields: country, languages.
skip_tls_verification	bool	Skip TLS verification.
remove_base64_images	bool	Drop base64 images from markdown output.
fast_mode	bool	Faster scrapes with reduced fidelity.
block_ads	bool	Block ads and cookie popups.
proxy	str	Proxy mode. Values: "basic", "stealth", "enhanced", "auto".
max_age	int	Use cached data up to this age (milliseconds).
store_in_cache	bool	Cache the result.
lockdown	bool	Only serve cached results, never make an outbound request.
profile	dict	Persistent browser profile. Keys: name, save_changes.
audit_metadata	AuditMetadata	User attribution for SIEM logging. Field: username.

Interact

Why use it

Use interact when a page requires browser actions or code execution after a scrape starts.

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 non-empty.

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 from scrape response")

result = client.interact(job_id, prompt="Click the pricing tab and summarize the plans.")

Parameters

Parameter	Type	Description
job_id	str	Scrape job ID from document.metadata.scrape_id.
code	str	Code to run in the browser session. Provide code or prompt (at least one required).
prompt	str	Natural-language instruction for the browser agent. Provide code or prompt (at least one required). Keyword-only.
language	str	Runtime. Values: "python", "node", "bash". Default: "node".
timeout	int	Execution timeout in seconds (1–300).

Stop session

client.stop_interaction(job_id) ends the scrape-bound browser session. Returns BrowserDeleteResponse with success, session_duration_ms, credits_billed.

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 an alias for Firecrawl; AsyncFirecrawlApp is an alias for AsyncFirecrawl.
• Pydantic models handle camelCase conversion for the API wire format; always use snake_case in Python.

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