> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-eiyh7n.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 is the canonical quickstart for external agents integrating with Firecrawl using the official Python SDK. 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") ``` Constructor parameters: | Parameter | Type | Default | Description | | ---------------- | ------- | ----------------------------- | ---------------------------------------------------------- | | `api_key` | `str` | `FIRECRAWL_API_KEY` env var | API key. Omit for keyless free tier (rate-limited per IP). | | `api_url` | `str` | `"https://api.firecrawl.dev"` | Base URL. | | `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. | 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 pages. Returns search results grouped by source type, optionally with scraped content. * **`scrape`** — Use when you already have a URL and want its content. Returns markdown, HTML, structured data, screenshots, or other formats. * **`interact`** — Use when the page needs post-scrape browser actions like clicking, filling forms, or executing code in the browser sandbox. ## Search ### Why use it Search the web and optionally scrape each result in one call. Start here when you have a question or topic but not a specific URL. ### 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=ScrapeOptions(formats=["markdown"]), ) for item in results.web or []: print(item.url, item.markdown[:200] if item.markdown else "") ``` ### Parameters All parameters are keyword-only and optional unless noted. | Parameter | Type | Description | | --------------------- | ------------------------- | -------------------------------------------------------------------------------- | | `query` | `str` | **Required (positional).** The search query. | | `sources` | `list[str \| Source]` | Source types to search (e.g. `"web"`, `"news"`, `"images"`). | | `categories` | `list[str \| Category]` | Filter by category (e.g. `"github"`, `"research"`, `"pdf"`, `"developer"`). | | `include_domains` | `list[str]` | Restrict results to these domains. Mutually exclusive with `exclude_domains`. | | `exclude_domains` | `list[str]` | Exclude results from these domains. | | `limit` | `int` | Max results to return. | | `tbs` | `str` | Time-based search filter (e.g. `"qdr:d"` for past day, `"qdr:w"` for past week). | | `location` | `str` | Geographic location for results. | | `ignore_invalid_urls` | `bool` | Exclude URLs invalid for other Firecrawl endpoints. | | `timeout` | `int` | Timeout in milliseconds. | | `highlights` | `bool` | Generate query-relevant highlights. | | `scrape_options` | `ScrapeOptions` | Options applied when scraping each result. See Scrape parameters. | | `integration` | `str` | Integration identifier. | | `enterprise` | `list[str]` | Enterprise options (e.g. `"anon"`, `"zdr"`). | | `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection override. | ## Scrape ### Why use it Fetch and extract content from a single URL. Use when you have a specific page to read. ### Preferred SDK method ```python theme={null} client.scrape(url, **kwargs) ``` ### Example ```python theme={null} doc = client.scrape( "https://example.com", formats=["markdown", "links"], only_main_content=True, ) print(doc.markdown) print(doc.links) ``` ### Parameters All parameters are keyword-only and optional unless noted. | Parameter | Type | Description | | ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `str` | **Required (positional).** The URL to scrape. | | `formats` | `list[FormatOption]` | Output formats. String values: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Object variants also supported for `json`, `screenshot`, `changeTracking`, `attributes`, `question`, `highlights`. | | `headers` | `dict[str, str]` | Custom HTTP headers to send with the request. | | `include_tags` | `list[str]` | HTML tags to include exclusively. | | `exclude_tags` | `list[str]` | HTML tags to exclude. | | `only_main_content` | `bool` | Only return main content, excluding navbars/footers. | | `timeout` | `int` | Timeout in milliseconds. | | `wait_for` | `int` | Delay in ms before fetching content. | | `mobile` | `bool` | Emulate a mobile device. | | `parsers` | `list[str \| PDFParser]` | File processing parsers. PDF modes: `"fast"`, `"auto"`, `"ocr"`. | | `actions` | `list[Action]` | Browser actions to perform before scraping. Types: `WaitAction`, `ScreenshotAction`, `ClickAction`, `WriteAction`, `PressAction`, `ScrollAction`, `ScrapeAction`, `ExecuteJavascriptAction`, `PDFAction`. | | `location` | `Location` | Geolocation config 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` | Faster scraping with reduced accuracy. | | `use_mock` | `str` | Use a mock response. | | `block_ads` | `bool` | Block ads and cookie popups. | | `proxy` | `str` | Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. | | `max_age` | `int` | Use cached result if younger than this (ms). | | `store_in_cache` | `bool` | Whether to cache the result. | | `lockdown` | `bool` | Serve only cached results. No outbound request. | | `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `profile` | `dict` | Persistent browser storage profile with `name` and optional `save_changes`. | | `audit_metadata` | `AuditMetadata` | User attribution for SIEM logging with `username` field. | | `integration` | `str` | Integration identifier. | ## Interact ### Why use it Execute code or natural-language prompts in the browser sandbox associated with a scrape job. Use after a scrape to click buttons, fill forms, navigate, or extract additional data. ### Preferred SDK method ```python theme={null} client.interact(job_id, code=None, *, prompt=None, language="node", timeout=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.querySelector('button.load-more')?.click();", language="node", timeout=30, ) print(result.stdout) ``` ### Parameters | Parameter | Type | Default | Description | | ---------- | ----- | -------- | --------------------------------------------------------------------------------------- | | `job_id` | `str` | — | **Required (positional).** The scrape job ID from a prior scrape. | | `code` | `str` | `None` | Code to execute in the browser sandbox. Required if `prompt` is not provided. | | `prompt` | `str` | `None` | Natural-language instruction for the browser agent. Required if `code` is not provided. | | `language` | `str` | `"node"` | Runtime language: `"python"`, `"node"`, or `"bash"`. | | `timeout` | `int` | `None` | Execution timeout in seconds (1-300). | | `origin` | `str` | `None` | Request origin tag. | ### Related method ```python theme={null} client.stop_interaction(job_id) ``` Stops the interactive browser session and returns billing info. ## Notes * **Naming style:** All parameters use snake\_case. * **Deprecated aliases:** * `scrape_url()` → use `scrape()` instead. * `scrape_execute()` → use `interact()` instead. * `stop_interactive_browser()` and `delete_scrape_browser()` → use `stop_interaction()` instead. * `FirecrawlApp` → use `Firecrawl` instead (alias still works). * **Async client:** Use `AsyncFirecrawl` (aliased as `AsyncFirecrawlApp`) for async/await usage with the same method signatures. * **ScrapeOptions model:** The `ScrapeOptions` Pydantic model also includes `min_age` and `redact_pii` fields which are available when passing `scrape_options` to `search()` but are not direct kwargs on `scrape()`. ## 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`