> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-4ti4xi.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 Firecrawl via 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 client = Firecrawl(api_key="fc-YOUR_API_KEY") ``` The API key can also be set via the `FIRECRAWL_API_KEY` environment variable. If omitted, the client falls back to keyless free tier (rate-limited per IP). Constructor options: `api_key` (str), `api_url` (str, default `"https://api.firecrawl.dev"`), `timeout` (float), `max_retries` (int, default `3`), `backoff_factor` (float, default `0.5`). An async client is also available: `from firecrawl import AsyncFirecrawl`. ## When To Use What * **`search`**: Use when you start with a query and need to discover relevant URLs and their content. Returns results from web, news, and image sources. * **`scrape`**: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats. * **`interact`**: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session. ## Search ### Why use it Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction. ### Preferred SDK method ```python theme={null} client.search(query, **kwargs) ``` ### Example ```python theme={null} results = client.search( "firecrawl web scraping API", limit=5, scrape_options={"formats": ["markdown"]}, ) for item in results.web or []: print(item.get("title"), item.get("url")) ``` ### Parameters | Parameter | Type | Description | | --------------------- | ------------------------- | -------------------------------------------------------------------------------- | | `query` | `str` | The search query (first argument, required). | | `sources` | `list[str]` | Sources to search: `"web"`, `"news"`, `"images"`. | | `categories` | `list[str]` | Filter by category: `"github"`, `"research"`, `"pdf"`, `"developer"`. | | `include_domains` | `list[str]` | Restrict results to these domains. Cannot be used with `exclude_domains`. | | `exclude_domains` | `list[str]` | Exclude results from these domains. Cannot be used with `include_domains`. | | `limit` | `int` | Maximum number of results. Server default: `10`. | | `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 search. | | `ignore_invalid_urls` | `bool` | Ignore invalid URLs in results. | | `timeout` | `int` | Timeout in milliseconds. Server default: `60000`. | | `highlights` | `bool` | Generate query-relevant highlights. Default: `True`. | | `scrape_options` | `ScrapeOptions` | Nested scrape configuration applied to each result. | | `enterprise` | `list[str]` | Enterprise search options for ZDR. | | `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection overrides. | | `integration` | `str` | Integration identifier. | ### Return type `SearchData` with attributes: `web`, `news`, `images`, `developer`. Each is a list of result dicts or `None`. Access results via `results.web`, not `results.data`. ## Scrape ### Why use it Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more. ### Preferred SDK method ```python theme={null} client.scrape(url, **kwargs) ``` ### Example ```python theme={null} doc = client.scrape( "https://example.com", formats=["markdown", "html"], only_main_content=True, ) print(doc.markdown) ``` ### Parameters | Parameter | Type | Description | | ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `str` | The URL to scrape (first argument, required). | | `formats` | `list` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or typed dicts. Server default: `["markdown"]`. | | `only_main_content` | `bool` | Strip boilerplate, keep main content only. Server default: `True`. | | `headers` | `dict[str, str]` | Custom HTTP headers to send with the request. | | `include_tags` | `list[str]` | HTML tags to exclusively include. | | `exclude_tags` | `list[str]` | HTML tags to exclude. | | `timeout` | `int` | Timeout in milliseconds. Min: `1000`, max: `300000`. Server default: `60000`. | | `wait_for` | `int` | Delay in milliseconds before fetching content. | | `mobile` | `bool` | Emulate mobile device. | | `parsers` | `list` | Parser configurations (e.g. `"pdf"` or `{"type": "pdf", "mode": "auto"}`). Server default: `["pdf"]`. | | `actions` | `list[dict]` | Browser automation actions. See Actions table below. | | `location` | `Location` | Location settings: `{"country": "US", "languages": ["en-US"]}`. | | `skip_tls_verification` | `bool` | Skip TLS certificate verification. | | `remove_base64_images` | `bool` | Remove base64 images from markdown output. Server default: `True`. | | `fast_mode` | `bool` | Enable fast mode for faster scrapes. | | `block_ads` | `bool` | Block advertisements and cookie popups. Server default: `True`. | | `proxy` | `str` | Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. Server default: `"auto"`. | | `max_age` | `int` | Use cached result if younger than this many milliseconds. Server default: `172800000` (2 days). | | `store_in_cache` | `bool` | Cache the scrape result. Server default: `True`. | | `lockdown` | `bool` | Only serve cached results, never make outbound requests. | | `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection overrides. | | `audit_metadata` | `AuditMetadata` | User attribution for SIEM logging: `{"username": "..."}`. | | `profile` | `dict` | Persistent browser profile: `{"name": "...", "save_changes": True}`. | | `integration` | `str` | Integration identifier. | | `use_mock` | `str` | Use mock data. | #### Actions | Type | Fields | | ------------------- | ------------------------------------------------------------------------------ | | `wait` | `{"type": "wait", "milliseconds": int}` or `{"type": "wait", "selector": str}` | | `screenshot` | `{"type": "screenshot", "fullPage": bool, "quality": int}` | | `click` | `{"type": "click", "selector": str}` | | `write` | `{"type": "write", "text": str}` | | `press` | `{"type": "press", "key": str}` | | `scroll` | `{"type": "scroll", "direction": "up" \| "down", "selector": str}` | | `scrape` | `{"type": "scrape"}` | | `executeJavascript` | `{"type": "executeJavascript", "script": str}` | | `pdf` | `{"type": "pdf", "format": str, "landscape": bool, "scale": float}` | ## Interact ### Why use it Execute code or send natural-language prompts in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts. ### Preferred SDK method ```python theme={null} client.interact(job_id, code=None, *, prompt=None, language="node", timeout=None, origin=None) ``` ### Example ```python theme={null} doc = client.scrape("https://example.com", formats=["markdown"]) job_id = doc.metadata.get("jobId") result = client.interact(job_id, code="document.title", language="node") print(result.stdout) client.stop_interaction(job_id) ``` ### Parameters | Parameter | Type | Description | | ---------- | ----- | ---------------------------------------------------------------------- | | `job_id` | `str` | The scrape job ID (first argument, required). | | `code` | `str` | Code to execute in the browser sandbox (positional). | | `prompt` | `str` | Natural-language instruction for the browser agent (keyword-only). | | `language` | `str` | Execution language: `"python"`, `"node"`, `"bash"`. Default: `"node"`. | | `timeout` | `int` | Execution timeout in seconds. Range: 1-300. Server default: `30`. | | `origin` | `str` | Origin identifier for telemetry. | Either `code` or `prompt` must be provided. Use `client.stop_interaction(job_id)` to end the browser session. ## Notes * **Naming style**: All parameters use snake\_case. * **Deprecated aliases**: `scrape_url()` is deprecated in favor of `scrape()`. `scrape_execute()` is deprecated in favor of `interact()`. `stop_interactive_browser()` and `delete_scrape_browser()` are deprecated in favor of `stop_interaction()`. `FirecrawlApp` is deprecated in favor of `Firecrawl`. * **Async support**: Use `AsyncFirecrawl` for async/await usage with the same method signatures. * **Search return type**: Access results via `results.web`, `results.news`, `results.images`, `results.developer`. Accessing `results.data` raises `AttributeError` with guidance. ## 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`