> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8al6t2.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 with Firecrawl via the official Python SDK. It is generated from SDK source and the OpenAPI spec.

## Install

```bash theme={null}
pip install firecrawl
```

## 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()
```

## When To Use What

* **`search`** — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
* **`scrape`** — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
* **`interact`** — Use when a page needs browser automation after scraping — clicks, form fills, or post-scrape dynamic content extraction.

## Search

### Why use it

Search the web for a query and get results with titles, URLs, descriptions, and optionally full page content. Supports filtering by domain, time range, category, and source type.

### Preferred SDK method

```
app.search(query, **kwargs)
```

### Example

```python theme={null}
results = app.search("firecrawl web scraping", limit=5, scrape_options={"formats": ["markdown"]})

for result in results.web:
    print(result.title, result.url)
    print(result.markdown)  # available when scrape_options is set
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | `str` | The search query (max 500 chars). **Required.** |
| `limit` | `int` | Max results to return per source type. Default: `5` (SDK), `10` (API). Range: 1–100. |
| `sources` | `list[str \| Source]` | Source types: `"web"`, `"news"`, `"images"`, `"alexandria"`. Default: `["web"]`. |
| `categories` | `list[str \| Category]` | Filter by category: `"github"`, `"research"`, `"pdf"`, `"developer"`, `"gov"`. |
| `include_domains` | `list[str]` | Restrict results to these domains (hostnames only). Cannot combine with `exclude_domains`. |
| `exclude_domains` | `list[str]` | Exclude results from these domains. Cannot combine with `include_domains`. |
| `tbs` | `str` | Time-based filter. Predefined: `qdr:h` (hour), `qdr:d` (day), `qdr:w` (week), `qdr:m` (month), `qdr:y` (year). Custom: `cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`. Sort by date: `sbd:1`. Combinable. |
| `location` | `str` | Location for search results (city/region name). |
| `country` | `str` | ISO 3166-1 alpha-2 country code. |
| `highlights` | `bool` | Return query-relevant highlights. |
| `timeout` | `int` | Timeout in milliseconds. Default: `300000`. |
| `ignore_invalid_urls` | `bool` | Skip invalid URLs instead of failing. |
| `scrape_options` | `ScrapeOptions \| dict` | Apply scrape options to each search result page to get full content. |
| `domain_tools` | `bool` | Include Alexandria tool contracts matched to result domains. |
| `tool_detail` | `"compact" \| "summary" \| "full"` | Detail level for returned tool contracts. Default: `"compact"`. |
| `integration` | `str` | Integration identifier. |
| `enterprise` | `list[str]` | Enterprise options: `"default"`, `"anon"`, `"zdr"`. |

## Scrape

### Why use it

Scrape a URL and get its content in your chosen format — markdown, HTML, JSON (with schema-based extraction), screenshots, and more. Supports browser actions, caching, proxies, and PDF parsing.

### Preferred SDK method

```
app.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` | The URL to scrape. **Required.** |
| `formats` | `list[FormatOption]` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, `"summary"`, `"audio"`, `"video"`, `"changeTracking"`, `"branding"`, `"product"`, `"menu"`, `"question"`, `"highlights"`. Default: `["markdown"]`. Some accept config dicts. |
| `only_main_content` | `bool` | Strip headers, navs, footers. Deterministic HTML filter, no LLM. Default: `true` (API). |
| `only_clean_content` | `bool` | Additional LLM-based boilerplate removal pass. Default: `false`. |
| `include_tags` | `list[str]` | Only include content from these HTML tags. |
| `exclude_tags` | `list[str]` | Exclude content from these HTML tags. |
| `headers` | `dict[str, str]` | Custom HTTP headers (cookies, user-agent, etc.). |
| `wait_for` | `int` | Extra delay in ms before fetching content, on top of smart-wait. Default: `0`. |
| `timeout` | `int` | Request timeout in ms. Min: 1000, default: 60000, max: 300000. |
| `mobile` | `bool` | Emulate a mobile device. Default: `false`. |
| `max_age` | `int` | Use cached result if younger than this (ms). Default: 172800000 (2 days). Set `0` to bypass cache. |
| `min_age` | `int` | Cache-only mode. Returns cached data if it exists, 404 otherwise. Set `1` to accept any cached data. |
| `store_in_cache` | `bool` | Cache this scrape result. |
| `actions` | `list[Action]` | Browser actions to perform before scraping (wait, click, type, scroll, screenshot, etc.). |
| `location` | `Location` | Geolocation: `Location(country="US", languages=["en"])`. |
| `parsers` | `list[str \| PDFParser]` | File parsers. Default: `["pdf"]`. PDF parser supports `mode` (`"fast"`, `"auto"`, `"ocr"`), `max_pages`, `pages`, `blocks`, `page_markers`. |
| `proxy` | `str` | Proxy type: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`. |
| `skip_tls_verification` | `bool` | Skip TLS cert verification. Default: `true` (API). |
| `remove_base64_images` | `bool` | Strip base64 images from output. |
| `block_ads` | `bool` | Block ads and cookie popups. |
| `fast_mode` | `bool` | Enable fast scraping mode. |
| `lockdown` | `bool` | Serve only cached results. |
| `check_prompt_injection` | `bool` | Scan content for prompt injection (adds 4 credits). |
| `redact_pii` | `bool \| RedactPIIOptions` | Redact personally identifiable information. |
| `profile` | `dict` | Persistent browser profile: `{"name": "my-profile", "save_changes": True}`. |
| `domain_tools` | `bool` | Return Alexandria tool contracts matched to the scraped domain. |
| `tool_detail` | `"compact" \| "summary" \| "full"` | Detail level for tool contracts. |
| `integration` | `str` | Integration identifier. |

## Interact

### Why use it

After scraping a page, interact with it in a live browser session — execute code or natural-language prompts to click buttons, fill forms, navigate, and extract dynamic content.

### Preferred SDK method

```
app.interact(job_id, code=None, *, prompt=None, language="node", timeout=None)
```

### Example

```python theme={null}
result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata.get("scrapeId")

response = app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max")
print(response.output)

result = app.interact(scrape_id, code="document.title", language="node")
print(result.result)

app.stop_interaction(scrape_id)
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `job_id` | `str` | The scrape job ID from a previous scrape's `metadata["scrapeId"]`. **Required.** |
| `code` | `str` | Code to execute in the browser sandbox. Provide `code` or `prompt`. Max 100,000 chars. |
| `prompt` | `str` | Natural-language instruction for the browser agent. Provide `code` or `prompt`. |
| `language` | `"python" \| "node" \| "bash"` | Language for code execution. Default: `"node"`. |
| `timeout` | `int` | Execution timeout in seconds. Min: 1, default: 30 (API), max: 300. |
| `origin` | `str` | Origin label for telemetry. |

### Stopping an interaction

Call `app.stop_interaction(job_id)` to close the browser session and stop billing.

## Notes

* **Deprecated aliases:** `scrape_url` → `scrape`, `scrape_execute` → `interact`, `stop_interactive_browser` / `delete_scrape_browser` → `stop_interaction`. Always use the preferred names.
* **Backward-compat class names:** `FirecrawlApp` is an alias for `Firecrawl`. Use `Firecrawl`.
* **Parameter naming:** All parameters use snake\_case. The SDK automatically converts to camelCase for the API.
* **Package name:** `firecrawl` (PyPI).
* **Async support:** Use `AsyncFirecrawl` for async/await patterns.
* **Base URL:** Defaults to `https://api.firecrawl.dev`. Override with `api_url` in the constructor for self-hosted instances.

## Source Of Truth

* `firecrawl/apps/python-sdk/firecrawl/v2/client.py`
* `firecrawl/apps/python-sdk/firecrawl/v2/types.py`
* `firecrawl/apps/python-sdk/firecrawl/client.py`
* `firecrawl-docs/api-reference/v2-openapi.json`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.