> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bz2qg.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 integrating Firecrawl with Python. Generated from SDK source and OpenAPI spec. ## Install ```bash theme={null} pip install firecrawl-py ``` Requires Python 3.8+. ## Authenticate ```python theme={null} from firecrawl import Firecrawl app = Firecrawl(api_key="fc-YOUR-API-KEY") ``` Or set the `FIRECRAWL_API_KEY` environment variable and omit `api_key`: ```python theme={null} app = Firecrawl() ``` Constructor parameters: | Parameter | Type | Default | | ---------------- | ------- | -------------------------------------------------- | | `api_key` | `str` | `None` (falls back to `FIRECRAWL_API_KEY` env var) | | `api_url` | `str` | `"https://api.firecrawl.dev"` | | `timeout` | `float` | `None` | | `max_retries` | `int` | `3` | | `backoff_factor` | `float` | `0.5` | An async client is also available: `from firecrawl import AsyncFirecrawl`. ## When To Use What * **search**: Start with a query, discover relevant URLs, and get their content in one call. * **scrape**: You already have a URL and want its page content as markdown, HTML, JSON, or other formats. * **interact**: The page needs clicks, form fills, or post-scrape browser actions on a live session. ## Search ### Why use it Search the web for a query and get scraped content from the top results. Combines discovery and content extraction in one call. ### Preferred SDK method `search(query, **kwargs)` ### Example ```python theme={null} results = app.search("firecrawl web scraping", limit=5) for result in results.web: print(result.title, result.url) print(result.markdown) ``` ### Parameters | Parameter | Type | Description | | --------------------- | ------------------------- | --------------------------------------------------------------------------------------- | | `query` | `str` | **Required.** Search query (max 500 chars). | | `limit` | `int` | Max results per source type. Default: `5` (SDK default). | | `sources` | `list` | Sources to search: `"web"`, `"news"`, `"images"`, or `Source` objects. | | `categories` | `list` | Category filters: `"github"`, `"research"`, `"pdf"`, `"developer"`. | | `include_domains` | `list[str]` | Restrict to these domains. Cannot combine with `exclude_domains`. | | `exclude_domains` | `list[str]` | Exclude these domains. Cannot combine with `include_domains`. | | `tbs` | `str` | Time-based filter (e.g. `"qdr:d"` past day, `"qdr:w"` past week, `"qdr:m"` past month). | | `location` | `str` | Geo-targeting location string. | | `ignore_invalid_urls` | `bool` | Exclude invalid URLs from results. | | `timeout` | `int` | Timeout in ms. Default: `300000`. | | `highlights` | `bool` | Generate query-relevant highlights. | | `scrape_options` | `ScrapeOptions` | Scrape options applied to each result page. | | `enterprise` | `list[str]` | Enterprise zero data retention options. | | `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `integration` | `str` | Integration identifier. | Response groups results by source: `results.web`, `results.news`, `results.images`, `results.developer`. ## Scrape ### Why use it Get the content of a single URL as markdown, HTML, JSON, screenshots, or other formats. ### Preferred SDK method `scrape(url, **kwargs)` ### Example ```python theme={null} result = app.scrape("https://example.com", formats=["markdown", "links"], only_main_content=True) print(result.markdown) print(result.links) ``` ### Parameters | Parameter | Type | Description | | ----------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `str` | **Required.** URL to scrape. | | `formats` | `list` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Also accepts format config dicts. Default: `["markdown"]`. | | `headers` | `dict[str, str]` | Custom HTTP headers. | | `include_tags` | `list[str]` | HTML tags to include. | | `exclude_tags` | `list[str]` | HTML tags to exclude. | | `only_main_content` | `bool` | Strip navbars, footers, boilerplate. Default: `true`. | | `timeout` | `int` | Timeout in ms. Default: `60000`. Min: `1000`, Max: `300000`. | | `wait_for` | `int` | Extra delay in ms before fetching content. | | `mobile` | `bool` | Emulate a mobile device. | | `parsers` | `list` | File processing controls. Accepts `"pdf"` or `{"type": "pdf", "mode": "fast"\|"auto"\|"ocr", "max_pages": int}`. | | `actions` | `list` | Browser actions before content capture: `WaitAction`, `ClickAction`, `WriteAction`, `PressAction`, `ScrollAction`, `ScreenshotAction`, `ScrapeAction`, `ExecuteJavascriptAction`, `PDFAction`. | | `location` | `Location` | Geo settings with `country` and `languages`. Country defaults to `"US"`. | | `skip_tls_verification` | `bool` | Skip TLS certificate verification. | | `remove_base64_images` | `bool` | Remove base64 images from markdown. Default: `true`. | | `fast_mode` | `bool` | Enable fast mode. | | `block_ads` | `bool` | Block ads and cookie popups. Default: `true`. | | `proxy` | `str` | Proxy type: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. Default: `"auto"`. | | `max_age` | `int` | Cache threshold in ms. Returns cached version if younger. Default: 2 days. | | `min_age` | `int` | Cache-only mode minimum age in ms. | | `store_in_cache` | `bool` | Store result in Firecrawl cache. Default: `true`. | | `lockdown` | `bool` | Cache-only, no outbound requests. | | `redact_pii` | `bool \| RedactPIIOptions` | Redact PII. Pass `True` for defaults or a `RedactPIIOptions` object. | | `threat_protection` | `ThreatProtectionOptions` | Threat protection override. | | `audit_metadata` | `AuditMetadata` | SIEM logging with `username` field. | | `profile` | `dict` | Persistent browser profile with `name` and optional `save_changes`. | | `integration` | `str` | Integration identifier. | ## Interact ### Why use it Control a live browser session tied to a scrape job. Click buttons, fill forms, navigate, and extract dynamic content using code or natural-language prompts. ### Preferred SDK method `interact(job_id, code=None, *, prompt=None, language="node", timeout=None, origin=None)` ### Example ```python theme={null} result = app.scrape("https://www.amazon.com", formats=["markdown"]) scrape_id = result.metadata.scrape_id app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max") response = app.interact(scrape_id, prompt="Click on the first result and tell me the price") print(response.output) app.stop_interaction(scrape_id) ``` ### Parameters | Parameter | Type | Description | | ---------- | ----------------------------------- | --------------------------------------------------------------------------- | | `job_id` | `str` | **Required.** Scrape job ID from `result.metadata.scrape_id`. | | `code` | `str` | Code to execute in the browser sandbox. One of `code` or `prompt` required. | | `prompt` | `str` | Natural-language instruction. One of `code` or `prompt` required. | | `language` | `Literal["python", "node", "bash"]` | Runtime for code execution. Default: `"node"`. | | `timeout` | `int` | Execution timeout in seconds. Min: 1, Max: 300. | | `origin` | `str` | Origin label for telemetry. | Stop the session when done: ```python theme={null} app.stop_interaction(scrape_id) ``` ## Notes * Parameter names use **snake\_case** (e.g. `only_main_content`, `include_tags`, `scrape_options`). * `include_domains` and `exclude_domains` on search are mutually exclusive. * `FirecrawlApp` is a deprecated alias for `Firecrawl`. Use `Firecrawl`. * `AsyncFirecrawlApp` is a deprecated alias for `AsyncFirecrawl`. * Deprecated method aliases (do not use in new code): * `scrape_execute()` → use `interact()` * `stop_interactive_browser()` / `delete_scrape_browser()` → use `stop_interaction()` * `scrape_url()` → use `scrape()` * `crawl_url()` → use `crawl()` * `map_url()` → use `map()` ## 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`