> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-1rj1nh.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 Canonical quickstart for external agents. Generated from SDK source (`firecrawl-py`) and the OpenAPI spec. Use this file to get an agent calling Firecrawl correctly in one pass. ## Install ```bash theme={null} pip install firecrawl-py ``` ## Authenticate ```python theme={null} from firecrawl import Firecrawl app = Firecrawl(api_key="fc-YOUR_API_KEY") # or read from env automatically: app = Firecrawl() # uses FIRECRAWL_API_KEY env var ``` Constructor parameters: ```python theme={null} app = Firecrawl( api_key="fc-...", # optional; falls back to FIRECRAWL_API_KEY api_url="https://api.firecrawl.dev", # optional timeout=None, # optional; default HTTP request timeout (seconds) max_retries=3, # optional backoff_factor=0.5, # optional ) ``` An async client is also available: `from firecrawl import AsyncFirecrawl`. No API key is required for `scrape`, `search`, and `interact` — they fall back to a keyless free tier (rate-limited per IP). ## When To Use What * **`search`**: Start with a text query and need to discover relevant URLs and content across the web. * **`scrape`**: Already have a URL and want page content (markdown, HTML, structured JSON, screenshots, etc.). * **`interact`**: The page needs clicks, form fills, or post-scrape browser actions — run code or a prompt against the live browser session. ## Search ### Why use it Search the web and optionally scrape each result. Returns categorized results (web, news, images) with optional content scraping. ### Preferred SDK method ```python theme={null} app.search(query, **options) ``` ### 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.url, item.title) ``` ### Parameters | Parameter | Type | Description | | --------------------- | ------------------------- | ----------------------------------------------------------------------------------- | | `query` | `str` | **Required.** The search query. | | `limit` | `int` | Max number of results. Default: `5`. | | `sources` | `list[str]` | Which result sources: `"web"`, `"news"`, `"images"`. | | `categories` | `list[str]` | Narrow web results: `"github"`, `"research"`, `"pdf"`, `"developer"`. | | `include_domains` | `list[str]` | Only include results from these domains. Mutually exclusive with `exclude_domains`. | | `exclude_domains` | `list[str]` | Exclude results from these domains. | | `tbs` | `str` | Time-based search filter (e.g. `"qdr:d"` for past day). | | `location` | `str` | Location string for geo-targeting. Note: plain string, not a `Location` object. | | `country` | `str` | ISO country code for geo-targeting. | | `ignore_invalid_urls` | `bool` | Exclude URLs invalid for other Firecrawl endpoints. | | `timeout` | `int` | Timeout in milliseconds. Default: `300000`. | | `highlights` | `bool` | Generate query-relevant highlights. Default: `True`. | | `scrape_options` | `ScrapeOptions` | Scrape options applied to each result page. | | `enterprise` | `list[str]` | Enterprise options (e.g. `["zdr"]` or `["anon"]`). | | `threat_protection` | `ThreatProtectionOptions` | Enterprise per-request threat config. | | `integration` | `str` | Integration identifier. | **Return type**: `SearchData` with properties `.web`, `.news`, `.images`. Accessing `.data` raises an `AttributeError` with guidance. ## Scrape ### Why use it Fetch a single URL and extract content in various formats: markdown, HTML, structured JSON, screenshots, audio, video, and more. Handles JavaScript rendering, ad blocking, proxies, and caching. ### Preferred SDK method ```python theme={null} app.scrape(url, **options) ``` ### Example ```python theme={null} doc = app.scrape( "https://example.com", formats=["markdown", "links"], only_main_content=True, ) print(doc.markdown) print(doc.links) ``` ### Parameters | Parameter | Type | Description | | ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `str` | **Required.** The URL to scrape. | | `formats` | `list` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"attributes"`, `"audio"`, `"video"`, `"branding"`, `"product"`, `"menu"`, `"changeTracking"`. Also accepts format config dicts. | | `headers` | `dict[str, str]` | Custom HTTP headers. | | `include_tags` | `list[str]` | HTML tags to include in extraction. | | `exclude_tags` | `list[str]` | HTML tags to exclude from extraction. | | `only_main_content` | `bool` | Strip boilerplate (nav, footer, etc.). | | `timeout` | `int` | Server-side timeout in milliseconds. | | `wait_for` | `int` | Wait before scraping in milliseconds (for JS rendering). | | `mobile` | `bool` | Emulate a mobile viewport. | | `parsers` | `list` | Parser config (e.g. PDF mode, max\_pages, blocks). | | `actions` | `list` | Browser actions: wait, click, write, press, scroll, scrape, executeJavascript, screenshot, pdf. | | `location` | `Location` | `Location(country=..., languages=[...])` for geo-targeting. | | `skip_tls_verification` | `bool` | Skip TLS certificate checks. | | `remove_base64_images` | `bool` | Strip base64-encoded images from output. | | `fast_mode` | `bool` | Enable fast mode (less rendering, faster response). | | `block_ads` | `bool` | Block ads and cookie popups. | | `proxy` | `str` | Proxy tier: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. | | `max_age` | `int` | Max age in ms of cached content. | | `store_in_cache` | `bool` | Store the result in Firecrawl's cache. | | `lockdown` | `bool` | Only serve cached results; never make an outbound request. | | `threat_protection` | `ThreatProtectionOptions` | Enterprise per-request threat config. | | `audit_metadata` | `AuditMetadata` | SIEM logging attribution (`username` field). | | `profile` | `dict` | Persistent browser profile across sessions. | | `integration` | `str` | Integration identifier. | | `auto_resume` | `bool` | SDK-only. Auto-resume large docs that outlive the request window. | ## Interact ### Why use it Execute code or a natural-language prompt against the live browser session from a previous scrape. Use it to click buttons, fill forms, navigate, or extract dynamic content that only appears after user interaction. ### Preferred SDK method ```python theme={null} app.interact(job_id, code=None, *, prompt=None, language="node", timeout=None) ``` ### 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.output) # When done, stop the session: app.stop_interaction(job_id) ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | --------------------------------------------------------------------------------------- | | `job_id` | `str` | **Required.** The scrape job ID from a previous `scrape` call. | | `code` | `str` | Code to execute in the browser sandbox. At least one of `code` or `prompt` is required. | | `prompt` | `str` | Natural-language prompt to execute. At least one of `code` or `prompt` is required. | | `language` | `"python" \| "node" \| "bash"` | Language of the code. Default: `"node"`. | | `timeout` | `int` | Execution timeout in seconds (1–300). | **Stop the session** when done: ```python theme={null} app.stop_interaction(job_id) ``` ## Notes * All parameter names use **snake\_case** (e.g. `only_main_content`, `skip_tls_verification`). * `SearchData` uses `.web`, `.news`, `.images` — accessing `.data` raises `AttributeError` with migration guidance. * **Deprecated aliases** (use the preferred names above): * `scrape_url` → `scrape` * `scrape_execute` → `interact` * `delete_scrape_browser` / `stop_interactive_browser` → `stop_interaction` * `FirecrawlApp` → `Firecrawl` * `AsyncFirecrawlApp` → `AsyncFirecrawl` ## 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`