Python Agent Quickstart

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

Getting Started

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Agent Quickstarts

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

Stop session

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

​Stop session

​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

Stop session

Notes

Source Of Truth