> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-823qpc.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 with Firecrawl via the Python SDK. Generated from SDK source and the OpenAPI spec. ## Install ```bash theme={null} pip install firecrawl-py ``` ## Authenticate ```python theme={null} from firecrawl import Firecrawl firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY") ``` Or use the `FIRECRAWL_API_KEY` environment variable: ```python theme={null} firecrawl = Firecrawl() ``` Constructor parameters: | Parameter | Type | Default | Description | | ---------------- | ------- | ----------------------------- | ------------------------------------------------------------------------------------------------- | | `api_key` | `str` | `None` | API key. Falls back to `FIRECRAWL_API_KEY` env var, then keyless free tier (rate-limited per IP). | | `api_url` | `str` | `"https://api.firecrawl.dev"` | Base API URL. | | `timeout` | `float` | `None` | Default request timeout in seconds. | | `max_retries` | `int` | `3` | Max retries for failed requests. | | `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`**: Start with a query and discover relevant pages. Returns URLs, titles, descriptions, and optionally scraped content. * **`scrape`**: You already have a URL and want structured page content — markdown, HTML, screenshots, JSON extraction, etc. * **`interact`**: The page needs post-scrape browser actions — clicking, typing, executing code, or natural-language browser instructions. ## Search ### Why use it Discover web pages matching a query. Optionally scrape each result for full content in one call. ### Preferred SDK method `firecrawl.search(query, **kwargs)` ### Example ```python theme={null} from firecrawl import Firecrawl firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY") results = firecrawl.search("firecrawl web scraping", limit=5) for result in results.web: print(result.title, result.url) ``` ### Parameters | Parameter | Type | Description | | --------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `query` | `str` | Search query. Required (first positional argument). | | `limit` | `int` | Max number of results per source type. Default `5`. | | `sources` | `list[str \| Source]` | Result sources: `"web"`, `"news"`, `"images"`. Defaults to `["web"]`. | | `categories` | `list[str \| Category]` | Narrow results: `"github"`, `"research"`, `"pdf"`, `"developer"`. | | `include_domains` | `list[str]` | Restrict to these domains. Mutually exclusive with `exclude_domains`. | | `exclude_domains` | `list[str]` | Exclude these domains. Mutually exclusive with `include_domains`. | | `tbs` | `str` | Time-based filter: `"qdr:h"` (hour), `"qdr:d"` (day), `"qdr:w"` (week), `"qdr:m"` (month), `"qdr:y"` (year), or custom date ranges. | | `location` | `str` | Location string for geo-targeted results (e.g. `"San Francisco,California,United States"`). | | `ignore_invalid_urls` | `bool` | Skip invalid URLs. Useful when piping results to other Firecrawl endpoints. | | `timeout` | `int` | Timeout in milliseconds. Default `300000`. | | `highlights` | `bool` | Generate query-relevant highlights. Defaults to `true` server-side. Set `False` for raw descriptions. | | `scrape_options` | `ScrapeOptions` | Scrape each result page. Same parameters as the scrape endpoint below. | | `enterprise` | `list[str]` | Enterprise options: `["zdr"]` for zero data retention, `["anon"]` for anonymized search. | | `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `integration` | `str` | Integration identifier for attribution. | Results are grouped by source: `results.web`, `results.news`, `results.images`, `results.developer`. ## Scrape ### Why use it Extract structured content from a single URL — markdown, HTML, screenshots, JSON extraction, audio, video, and more. ### Preferred SDK method `firecrawl.scrape(url, **kwargs)` ### Example ```python theme={null} result = firecrawl.scrape("https://example.com", formats=["markdown", "links"]) print(result.markdown) print(result.links) ``` ### Parameters | Parameter | Type | Description | | ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `url` | `str` | URL to scrape. Required (first positional argument). | | `formats` | `list[FormatOption]` | Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"` (or `"raw_html"`), `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"` (or `"change_tracking"`), `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Or format objects like `JsonFormat`, `QuestionFormat`, `HighlightsFormat`. | | `headers` | `dict[str, str]` | Custom HTTP headers. Use for cookies, auth tokens, user-agent. | | `include_tags` | `list[str]` | Only include content from these HTML tags. | | `exclude_tags` | `list[str]` | Exclude content from these HTML tags. | | `only_main_content` | `bool` | Extract only main content, excluding headers/navs/footers. | | `timeout` | `int` | Timeout in milliseconds. Min `1000`, max `300000`. Default `60000`. | | `wait_for` | `int` | Additional wait in milliseconds before scraping. Use for JS-rendered content. | | `mobile` | `bool` | Emulate a mobile device. | | `parsers` | `list` | Parser config: `["pdf"]` or `[PDFParser(mode="fast" \| "auto" \| "ocr", max_pages=N)]`. | | `actions` | `list` | Browser actions before scraping: `WaitAction`, `ScreenshotAction`, `ClickAction`, `WriteAction`, `PressAction`, `ScrollAction`, `ScrapeAction`, `ExecuteJavascriptAction`, `PDFAction`. | | `location` | `Location` | Location settings: `Location(country="US", languages=["en-US"])`. | | `skip_tls_verification` | `bool` | Skip TLS certificate verification. | | `remove_base64_images` | `bool` | Remove base64 images from markdown output. | | `fast_mode` | `bool` | Faster scrape with reduced accuracy. | | `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. `0` bypasses cache. Default `172800000` (2 days). | | `store_in_cache` | `bool` | Store result in Firecrawl cache. | | `lockdown` | `bool` | Serve only cached results, never make outbound requests. | | `threat_protection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `profile` | `dict` | Persistent browser profile: `{"name": "my-profile", "saveChanges": True}`. | | `audit_metadata` | `AuditMetadata` | User attribution for SIEM logging: `AuditMetadata(username="user")`. | | `integration` | `str` | Integration identifier. | ## Interact ### Why use it Continue interacting with a live browser session after scraping. Execute code or send natural-language prompts to control the page — click buttons, fill forms, navigate, and extract dynamic content. ### Preferred SDK method `firecrawl.interact(job_id, code=None, *, prompt=None, language="node", timeout=None)` ### Example ```python theme={null} result = firecrawl.scrape("https://www.amazon.com", formats=["markdown"]) scrape_id = result.metadata.scrape_id firecrawl.interact(scrape_id, prompt="Search for iPhone 16 Pro Max") response = firecrawl.interact(scrape_id, prompt="Click on the first result and tell me the price") print(response.output) firecrawl.stop_interaction(scrape_id) ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `job_id` | `str` | Scrape job ID. Required (first positional argument). Obtained from `result.metadata.scrape_id` of a previous scrape. | | `code` | `str` | Code to execute in the browser session. One of `code` or `prompt` is required. Second positional argument. | | `prompt` | `str` | Natural-language instruction for the browser agent. One of `code` or `prompt` is required. Keyword-only. | | `language` | `"python" \| "node" \| "bash"` | Language for code execution. Defaults to `"node"`. Keyword-only. | | `timeout` | `int` | Execution timeout in seconds (1-300). Keyword-only. | | `origin` | `str` | Origin identifier. Keyword-only. | Call `firecrawl.stop_interaction(job_id)` to end the browser session when done. ## Notes * **snake\_case parameters**: All parameters use snake\_case (e.g. `only_main_content`, `include_tags`, `scrape_options`). The SDK converts to camelCase for the API. * **Format string aliases**: Both camelCase and snake\_case format strings are accepted (e.g. `"rawHtml"` and `"raw_html"` both work). * **SearchData structure**: Access results via `results.web`, `results.news`, `results.images`, or `results.developer`. Accessing `results.data` raises `AttributeError`. * **Pydantic models**: Return types (`Document`, `SearchData`, `BrowserExecuteResponse`) are Pydantic models with attribute-style access. * **Deprecated aliases**: `FirecrawlApp` -> `Firecrawl`, `scrape_execute` -> `interact`, `stop_interactive_browser` / `delete_scrape_browser` -> `stop_interaction`, `scrape_url` -> `scrape`. ## Source Of Truth * SDK source: `firecrawl/apps/python-sdk/firecrawl/v2/client.py`, `firecrawl/apps/python-sdk/firecrawl/v2/types.py` * OpenAPI spec: `firecrawl-docs/api-reference/v2-openapi.json`