> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-l3hcjj.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` **v4.41.0**) and the v2 OpenAPI spec. Method names, parameters, and types match the v2 client.

## Install

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

Requires Python >= 3.8.

## Authenticate

```python theme={null}
import os
from firecrawl import Firecrawl

client = Firecrawl(api_key=os.environ.get("FIRECRAWL_API_KEY"))
# client = Firecrawl(api_key="fc-...", api_url="https://api.firecrawl.dev")
```

## When To Use What

* **`search`**: use when you start with a query and need discovery.
* **`scrape`**: use when you already have a URL and want page content.
* **`interact`**: use when the page needs clicks, forms, or post-scrape browser actions. Requires a `scrape_id` from a prior scrape.

## Search

### Why use it

Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with `site:`, for example `site:docs.firecrawl.dev crawl webhooks`.

### Preferred SDK method

`client.search(query, **options)` → `SearchData`

### Example

```python theme={null}
results = client.search(
    "site:docs.firecrawl.dev webhook retries",
    sources=["web"],
    limit=5,
    scrape_options=ScrapeOptions(
        formats=["markdown"],
        only_main_content=True,
    ),
)

for item in results.web or []:
    print(getattr(item, "url", None), getattr(item, "title", None))
```

**Wrong turn to avoid:** `search()` does not return `{ data: [...] }`. Web results are in `result.web`, news in `result.news`, images in `result.images`.

### Parameters

| Parameter             | Type            | Description                                                               |
| --------------------- | --------------- | ------------------------------------------------------------------------- |
| `query`               | `str`           | Search query. Use `site:example.com` to limit to a domain.                |
| `sources`             | `list[str]`     | Which source indexes to search: `"web"`, `"news"`, `"images"`.            |
| `categories`          | `list[str]`     | Filter by category: `"developer"`, `"research"`, `"pdf"`, `"github"`.     |
| `include_domains`     | `list[str]`     | Only include these domains. Cannot combine with `exclude_domains`.        |
| `exclude_domains`     | `list[str]`     | Exclude these domains. Cannot combine with `include_domains`.             |
| `limit`               | `int`           | Max results. Default: `5` (SDK model default).                            |
| `tbs`                 | `str`           | Time-based filter (e.g. `qdr:d` for past day, `qdr:w` for past week).     |
| `location`            | `str`           | Localized results (plain string, not a `Location` object).                |
| `ignore_invalid_urls` | `bool`          | Drop URLs that cannot be scraped.                                         |
| `highlights`          | `bool`          | Return query-relevant text highlights. Defaults to `true` server-side.    |
| `timeout`             | `int`           | Request timeout in milliseconds. Default: `300000`.                       |
| `scrape_options`      | `ScrapeOptions` | Scrape each search result (see Scrape parameters).                        |
| `enterprise`          | `list[str]`     | Enterprise options: `"zdr"` (zero data retention), `"anon"` (anonymized). |

## Scrape

### Why use it

Fetch structured content from a URL in one or more formats. Use when you already have the URL.

### Preferred SDK method

`client.scrape(url, **options)` → `Document`

### Example

```python theme={null}
doc = client.scrape(
    "https://example.com/pricing",
    formats=[
        "markdown",
        {"type": "json", "prompt": "Extract plan names and prices."},
    ],
    only_main_content=True,
)

print(doc.markdown)
print(doc.json)
```

### Parameters

| Parameter               | Type             | Description                                                                                                 |
| ----------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `url`                   | `str`            | URL to scrape.                                                                                              |
| `formats`               | `list`           | Output formats (see below).                                                                                 |
| `headers`               | `dict[str, str]` | Custom request headers.                                                                                     |
| `include_tags`          | `list[str]`      | Include only these HTML tags.                                                                               |
| `exclude_tags`          | `list[str]`      | Exclude these HTML tags.                                                                                    |
| `only_main_content`     | `bool`           | Strip nav, footer, boilerplate.                                                                             |
| `timeout`               | `int`            | Timeout in milliseconds.                                                                                    |
| `wait_for`              | `int`            | Wait for page to render (milliseconds).                                                                     |
| `mobile`                | `bool`           | Use a mobile viewport.                                                                                      |
| `parsers`               | `list`           | File parsing controls (e.g. `{"type": "pdf", "mode": "auto", "max_pages": 5}`).                             |
| `actions`               | `list[dict]`     | Pre-scrape browser actions (click, wait, write, press, scroll, scrape, executeJavascript, screenshot, pdf). |
| `location`              | `Location`       | Geo/language-aware scraping. `Location(country="US", languages=["en-US"])`.                                 |
| `skip_tls_verification` | `bool`           | Skip TLS verification.                                                                                      |
| `remove_base64_images`  | `bool`           | Drop base64 images from markdown.                                                                           |
| `fast_mode`             | `bool`           | Faster scrapes with reduced fidelity.                                                                       |
| `block_ads`             | `bool`           | Block ads and cookie popups.                                                                                |
| `proxy`                 | `str`            | Proxy mode: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`.                                                 |
| `max_age`               | `int`            | Use cached data up to this age (milliseconds).                                                              |
| `store_in_cache`        | `bool`           | Cache the result.                                                                                           |
| `lockdown`              | `bool`           | Serve only cached results; never make outbound request.                                                     |
| `profile`               | `dict`           | Persistent browser profile: `{"name": "my-session", "saveChanges": True}`.                                  |

**Format options:**

String formats: `"markdown"`, `"html"`, `"rawHtml"` (or `"raw_html"`), `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"` (or `"change_tracking"`), `"attributes"`, `"branding"`, `"audio"`, `"video"`.

Object formats:

* `{"type": "json", "prompt": "...", "schema": {...}}` — at least one of `prompt` or `schema` required.
* `{"type": "question", "question": "..."}` — question-answer extraction.
* `{"type": "highlights", "query": "..."}` — relevant source-text extraction.
* `{"type": "screenshot", "full_page": True, "quality": 80, "viewport": {"width": 1280, "height": 720}}`
* `{"type": "changeTracking", "modes": ["git-diff"], "tag": "..."}` — `modes` required.
* `{"type": "attributes", "selectors": [{"selector": "a", "attribute": "href"}]}`

## Interact

### Why use it

Control the browser session tied to a scrape job. Use for clicks, form fills, code execution, or natural-language instructions after a scrape creates a session. Requires `scrape_id` from `document.metadata.scrape_id`.

### Preferred SDK method

`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.scrape_id if doc.metadata else None
if not job_id:
    raise RuntimeError("Missing scrape_id")

# Natural-language interaction
result = client.interact(job_id, prompt="Click the pricing tab and summarize the plans.")

# Or code-based interaction
code_result = client.interact(
    job_id,
    code="print(await page.title())",
    language="python",
    timeout=60,
)

# Clean up
client.stop_interaction(job_id)
```

### Parameters

| Parameter  | Type  | Description                                                                                   |
| ---------- | ----- | --------------------------------------------------------------------------------------------- |
| `job_id`   | `str` | Scrape job ID from `document.metadata.scrape_id`.                                             |
| `code`     | `str` | Code to run in the browser session (optional if `prompt` is set).                             |
| `prompt`   | `str` | Natural-language instruction for the browser agent (keyword-only; optional if `code` is set). |
| `language` | `str` | Runtime: `"python"`, `"node"`, `"bash"`. Default: `"node"`.                                   |
| `timeout`  | `int` | Execution timeout in seconds.                                                                 |

At least one of `code` or `prompt` must be provided.

**Stop session:** `client.stop_interaction(job_id)` ends the browser session.

## Notes

* Deprecated aliases: `scrape_execute` → `interact`; `stop_interactive_browser` / `delete_scrape_browser` → `stop_interaction`.
* The top-level `Firecrawl` client exposes v2 methods directly; v1 remains under `client.v1`.
* `FirecrawlApp` is a direct alias for `Firecrawl`.
* `search()` location is a plain `str`, not a `Location` object (unlike `scrape()`).
* `SearchRequest` model defaults: `limit=5`, `timeout=300000`.

## Source Of Truth

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