> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-4orfll.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. # Firecrawl Python Agent Quickstart This file is the canonical quickstart for external agents integrating with Firecrawl using the Python SDK. It is generated from SDK source and OpenAPI spec. ## Install ```bash theme={null} pip install firecrawl-py ``` ## Authenticate ```python theme={null} from firecrawl import Firecrawl app = Firecrawl(api_key="fc-YOUR_API_KEY") ``` The API key can also be set via the `FIRECRAWL_API_KEY` environment variable. Omitting the key uses the keyless free tier (rate-limited per IP). **Client options:** | Option | Type | Default | Description | | ---------------- | ------- | ----------------------------- | -------------------------------------------- | | `api_key` | `str` | `FIRECRAWL_API_KEY` env var | API key for authentication | | `api_url` | `str` | `"https://api.firecrawl.dev"` | Base URL for the API | | `timeout` | `float` | `None` | Default request timeout in seconds | | `max_retries` | `int` | `3` | Max automatic retries for transient failures | | `backoff_factor` | `float` | `0.5` | Exponential backoff factor for retries | ## When To Use What * **`search`**: Use when you start with a query and need to discover relevant pages. Returns ranked results with optional scraping of each result. * **`scrape`**: Use when you already have a URL and want its content in markdown, HTML, JSON, or other formats. * **`interact`**: Use when a page needs post-scrape browser actions — clicking, filling forms, running code, or prompting an AI agent in the browser. ## Search ### Why use it Search the web for a query and get back ranked results. Optionally scrape each result page inline by passing `scrape_options`. ### Preferred SDK method ```python theme={null} app.search(query, **kwargs) ``` ### Example ```python theme={null} results = app.search( "firecrawl web scraping API", limit=5, scrape_options={"formats": ["markdown"]}, ) for item in results.web or []: print(item.title, item.url) ``` ### Parameters | Parameter | Type | Description | | --------------------- | ------------------------- | -------------------------------------------------------------------------------- | | `query` | `str` | **Required.** The search query (max 500 chars). | | `limit` | `int` | Max results to return. Default: `5`. | | `sources` | `list` | Which result sources to include: `"web"`, `"news"`, `"images"`. | | `categories` | `list` | Filter results by category: `"github"`, `"research"`, `"pdf"`, `"developer"`. | | `include_domains` | `list[str]` | Restrict results to these domains. Cannot combine with `exclude_domains`. | | `exclude_domains` | `list[str]` | Exclude results from these domains. Cannot combine with `include_domains`. | | `tbs` | `str` | Time-based search filter (e.g. `"qdr:d"` for past day, `"qdr:w"` for past week). | | `location` | `str` | Location string for geo-targeted results. | | `ignore_invalid_urls` | `bool` | Ignore invalid URLs in results. | | `timeout` | `int` | Timeout in milliseconds. Default: `300000`. | | `highlights` | `bool` | Generate query-relevant highlights. Default: `True`. | | `scrape_options` | `ScrapeOptions \| dict` | Scrape options applied to each result page. | | `enterprise` | `list[str]` | Enterprise options: `["zdr"]` or `["anon"]`. | | `threat_protection` | `ThreatProtectionOptions` | Enterprise per-request threat protection override. | | `integration` | `str` | Integration identifier for tracking. | **Returns:** `SearchData` with optional `.web`, `.news`, and `.images` attributes. ## Scrape ### Why use it Scrape a single URL and get its content as markdown, HTML, structured JSON, screenshots, or other formats. ### Preferred SDK method ```python theme={null} app.scrape(url, **kwargs) ``` ### Example ```python theme={null} doc = app.scrape( "https://example.com", formats=["markdown", "links"], only_main_content=True, ) print(doc.markdown) ``` ### Parameters | Parameter | Type | Description | | ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `str` | **Required.** The URL to scrape. | | `formats` | `list` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or dicts like `{"type": "question", "question": "..."}` and `{"type": "highlights", "query": "..."}`. | | `only_main_content` | `bool` | Extract only the main content, excluding headers/navs/footers. | | `include_tags` | `list[str]` | HTML tags to include in output. | | `exclude_tags` | `list[str]` | HTML tags to exclude from output. | | `timeout` | `int` | Timeout in milliseconds (1000–300000). | | `wait_for` | `int` | Delay in ms before fetching content. | | `mobile` | `bool` | Emulate a mobile device. | | `headers` | `dict[str, str]` | Custom HTTP headers to send with the request. | | `actions` | `list` | Browser actions before scraping: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`. | | `parsers` | `list` | Parser configs. Include `"pdf"` to extract PDF content to markdown. | | `location` | `Location` | Geo-location with `country` and `languages` fields. | | `skip_tls_verification` | `bool` | Skip TLS certificate verification. | | `remove_base64_images` | `bool` | Remove base64 images from output. | | `fast_mode` | `bool` | Enable fast mode (less accuracy). | | `block_ads` | `bool` | Block ads and cookie popups. | | `proxy` | `str` | Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. | | `max_age` | `int` | Use cached result if younger than this (ms). | | `store_in_cache` | `bool` | Store result in Firecrawl cache. | | `lockdown` | `bool` | Serve from cache only; never makes outbound request. | | `redact_pii` | `bool` | Redact PII from returned content. | | `audit_metadata` | `AuditMetadata` | User attribution for SIEM logging (`username` field). | | `profile` | `dict` | Persistent browser profile for session continuity. | | `integration` | `str` | Integration identifier. | | `threat_protection` | `ThreatProtectionOptions` | Enterprise per-request threat protection override. | **Returns:** `Document` with attributes like `markdown`, `html`, `raw_html`, `links`, `images`, `screenshot`, `metadata`, etc. ## Interact ### Why use it Execute code or send a natural-language prompt in the browser session of a previous scrape job. Use this for clicking buttons, filling forms, navigating multi-step flows, or running arbitrary JavaScript/Python/Bash in the browser sandbox. ### Preferred SDK method ```python theme={null} app.interact(job_id, code=None, prompt=None, **kwargs) ``` ### Example ```python theme={null} doc = app.scrape("https://example.com", formats=["markdown"]) job_id = doc.metadata.get("jobId") result = app.interact( job_id, code="document.querySelector('button.load-more').click();", language="node", timeout=30, ) print(result.stdout) ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------- | | `job_id` | `str` | **Required.** The scrape job ID. | | `code` | `str` | Code to execute. One of `code` or `prompt` is required. | | `prompt` | `str` | Natural-language instruction for the AI browser agent. One of `code` or `prompt` is required. | | `language` | `"python" \| "node" \| "bash"` | Execution language. Default: `"node"`. | | `timeout` | `int` | Execution timeout in seconds (1–300). | **Returns:** `BrowserExecuteResponse` with `success`, `stdout`, `stderr`, `result`, `exit_code`, `killed`, `error`. **Stop the session:** ```python theme={null} app.stop_interaction(job_id) ``` ## Notes * All parameter names use **snake\_case** (e.g. `only_main_content`, `skip_tls_verification`, `scrape_options`). * `include_domains` and `exclude_domains` on search are mutually exclusive. * The `SearchData` return type has `.web`, `.news`, and `.images` attributes. Accessing `.data` raises an `AttributeError` with migration guidance. * An async client is available: `from firecrawl import AsyncFirecrawl`. * **Deprecated aliases** (use the preferred names instead): * `scrape_url()` → `scrape()` * `scrape_execute()` → `interact()` * `stop_interactive_browser()` / `delete_scrape_browser()` → `stop_interaction()` * `FirecrawlApp` → `Firecrawl` ## Source Of Truth * `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`