> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-qzjftw.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Python Agent Quickstart > Canonical Firecrawl Python quickstart for external agents using search, scrape, and interact. Canonical Firecrawl Python quickstart for agents. Generated from SDK source (`firecrawl-py` **v4.22.1**) and the v2 OpenAPI spec. ## Install ```bash theme={null} pip install firecrawl-py ``` ## Authenticate ```python theme={null} 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 ```python theme={null} 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 ```python theme={null} 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 ```python theme={null} 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`