> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bb4v8.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 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 ```bash theme={null} pip install firecrawl-py ``` ## Authenticate ```py 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") ``` ## 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 ```py theme={null} 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 ```py theme={null} 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 ```py 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 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`