> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-qa59sd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Elixir Agent Quickstart

> Canonical Firecrawl Elixir quickstart for external agents using search, scrape, and interact.

# Firecrawl Elixir Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (`firecrawl` hex package, `firecrawl/apps/elixir-sdk`) and the v2 OpenAPI spec. Function names and parameters match the auto-generated client.

## Install

```elixir theme={null}
# mix.exs
defp deps do
  [
    {:firecrawl, "~> 1.9"}
  ]
end
```

## Authenticate

```elixir theme={null}
# Option 1: Application config (config/config.exs)
config :firecrawl, api_key: "fc-YOUR_API_KEY"

# Option 2: Per-request option
Firecrawl.search_and_scrape([query: "example"], api_key: "fc-YOUR_API_KEY")
```

All functions accept `api_key` and `base_url` (defaults to `https://api.firecrawl.dev/v2`) as options in the last keyword list argument. If no API key is provided, requests fall back to a keyless free tier (rate-limited per IP).

## When To Use What

* `search_and_scrape`: use when you start with a query and need discovery.
* `scrape_and_extract_from_url`: use when you already have a URL and want page content.
* `interact_with_scrape_browser_session`: use when the page needs clicks, forms, or post-scrape browser actions.

## Search

### Why use it

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with.

### Preferred SDK method

`Firecrawl.search_and_scrape(params, opts)` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`

Bang variant: `Firecrawl.search_and_scrape!(params, opts)` raises on error.

### Example

```elixir theme={null}
{:ok, response} = Firecrawl.search_and_scrape(
  query: "site:docs.firecrawl.dev webhooks",
  limit: 5,
  scrape_options: [formats: ["markdown"]]
)

# response.body contains the parsed JSON response
for item <- response.body["data"]["web"] || [] do
  IO.puts("#{item["url"]} #{item["title"]}")
end
```

### Parameters

Parameters are passed as a keyword list (first argument). All are optional except `query`.

| Parameter             | Type                 | Description                                               | When to use                             |
| --------------------- | -------------------- | --------------------------------------------------------- | --------------------------------------- |
| `query`               | `:string` (required) | The search query.                                         | Always required.                        |
| `sources`             | `{:list, :any}`      | Sources to search.                                        | When you want news or image results.    |
| `categories`          | `{:list, :any}`      | Filter by category.                                       | When filtering by category.             |
| `include_domains`     | `{:list, :string}`   | Restrict results to these domains.                        | When targeting specific sites.          |
| `exclude_domains`     | `{:list, :string}`   | Exclude results from these domains.                       | When filtering out specific sites.      |
| `limit`               | `:integer`           | Max results to return.                                    | When you need to cap results.           |
| `tbs`                 | `:string`            | Time-based filter (e.g. `"qdr:d"`).                       | When you need time-constrained results. |
| `location`            | `:string`            | Location for localized results.                           | When you want geo-targeted results.     |
| `country`             | `:string`            | ISO country code for geo-targeting.                       | When you want country-specific results. |
| `ignore_invalid_urls` | `:boolean`           | Ignore invalid URLs.                                      | When piping into scrape/interact.       |
| `timeout`             | `:integer`           | Timeout in milliseconds.                                  | When the default is too short.          |
| `highlights`          | `:boolean`           | Generate query-relevant highlights.                       | Set `false` for raw descriptions.       |
| `scrape_options`      | `:keyword_list`      | Scrape options per result (same fields as scrape params). | When you want full page content.        |
| `enterprise`          | `{:list, :string}`   | Enterprise options (`"anon"`, `"zdr"`).                   | Enterprise ZDR use cases.               |

## Scrape

### Why use it

Use scrape when you already have a URL and want structured content in one or more formats.

### Preferred SDK method

`Firecrawl.scrape_and_extract_from_url(params, opts)` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`

Bang variant: `Firecrawl.scrape_and_extract_from_url!(params, opts)` raises on error.

### Example

```elixir theme={null}
{:ok, response} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com/pricing",
  formats: ["markdown"],
  only_main_content: true
)

IO.puts(response.body["data"]["markdown"])
```

### Parameters

Parameters are passed as a keyword list (first argument). All are optional except `url`.

| Parameter               | Type                                | Description                                   | When to use                                |
| ----------------------- | ----------------------------------- | --------------------------------------------- | ------------------------------------------ |
| `url`                   | `:string` (required)                | The URL to scrape.                            | Always required.                           |
| `formats`               | `{:list, :any}`                     | Output formats (e.g. `["markdown", "html"]`). | Always — controls what data you get back.  |
| `headers`               | `:any`                              | Custom HTTP headers as a map.                 | When you need cookies, user-agent, etc.    |
| `include_tags`          | `{:list, :string}`                  | HTML tags to include.                         | When you only want specific tags.          |
| `exclude_tags`          | `{:list, :string}`                  | HTML tags to exclude.                         | When filtering out specific tags.          |
| `only_main_content`     | `:boolean`                          | Strip nav, footer, boilerplate.               | When you want clean content only.          |
| `timeout`               | `:integer`                          | Timeout in milliseconds.                      | When the default is too short.             |
| `wait_for`              | `:integer`                          | Wait time in ms after page load.              | When the page needs JS rendering time.     |
| `mobile`                | `:boolean`                          | Emulate mobile device.                        | For mobile-specific content.               |
| `parsers`               | `{:list, :any}`                     | Parser configs (e.g. PDF).                    | When scraping PDF files.                   |
| `actions`               | `{:list, :any}`                     | Pre-scrape browser actions.                   | When you need to interact before scraping. |
| `location`              | `:keyword_list`                     | Geolocation settings.                         | For geo-targeted content.                  |
| `skip_tls_verification` | `:boolean`                          | Skip TLS verification.                        | For sites with invalid certs.              |
| `remove_base64_images`  | `:boolean`                          | Remove base64 images.                         | For smaller output.                        |
| `block_ads`             | `:boolean`                          | Block ads.                                    | When ads interfere with extraction.        |
| `proxy`                 | `{:in, [:basic, :enhanced, :auto]}` | Proxy type.                                   | For anti-bot protection.                   |
| `max_age`               | `:integer`                          | Max cache age.                                | When cached data is acceptable.            |
| `min_age`               | `:integer`                          | Min cache age.                                | When you only want cached data.            |
| `store_in_cache`        | `:boolean`                          | Cache the result.                             | Set `false` for data protection.           |
| `lockdown`              | `:boolean`                          | Serve from cache only.                        | For ZDR-like behavior.                     |
| `redact_pii`            | `:boolean`                          | Redact PII from output.                       | When output may contain personal info.     |
| `zero_data_retention`   | `:boolean`                          | Enable zero data retention.                   | For ZDR compliance.                        |
| `profile`               | `:keyword_list`                     | Persistent browser profile.                   | When you need state to persist.            |
| `audit_metadata`        | `:keyword_list`                     | SIEM metadata (keys: `username`).             | Enterprise audit logging.                  |

## Interact

### Why use it

Use `interact_with_scrape_browser_session` for code execution in the browser session tied to a scrape job. For multi-step interactive flows, prefer this over scrape-time `actions`.

### Preferred SDK method

`Firecrawl.interact_with_scrape_browser_session(job_id, params, opts)` → `{:ok, Req.Response.t()} | {:error, Exception.t()}`

Bang variant: `Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts)` raises on error.

### Example

```elixir theme={null}
{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com",
  formats: ["markdown"]
)

job_id = scrape_response.body["data"]["metadata"]["scrapeId"]

{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
  code: "console.log(await page.title());",
  language: :node
)

IO.puts(result.body["stdout"])

# Stop the session when done
Firecrawl.stop_interactive_scrape_browser_session(job_id)
```

### Parameters

The first argument is the `job_id` (path parameter). Remaining parameters are a keyword list.

| Parameter  | Type                             | Description                             | When to use                          |
| ---------- | -------------------------------- | --------------------------------------- | ------------------------------------ |
| `job_id`   | `String.t()` (required, 1st arg) | The scrape job ID.                      | Always required.                     |
| `code`     | `:string` (required)             | Code to execute in the browser session. | Always required.                     |
| `language` | `{:in, [:python, :node, :bash]}` | Runtime language. Default: `:node`.     | When your code is in Python or Bash. |
| `timeout`  | `:integer`                       | Execution timeout in seconds.           | When execution may take longer.      |

### Return value

The response body contains: `success`, `cdpUrl`, `liveViewUrl`, `interactiveLiveViewUrl`, `output`, `stdout`, `result`, `stderr`, `exitCode`, `killed`, `error`.

### Stop session

`Firecrawl.stop_interactive_scrape_browser_session(job_id, opts)` — ends the browser session.

## Notes

* The Elixir SDK is auto-generated from the OpenAPI spec. Function names follow the OpenAPI operation IDs rather than simplified aliases.
* Function name mapping to other SDKs:
  * `search_and_scrape` = `search` in other SDKs
  * `scrape_and_extract_from_url` = `scrape` in other SDKs
  * `interact_with_scrape_browser_session` = `interact` in other SDKs
  * `stop_interactive_scrape_browser_session` = `stopInteraction` / `stop_interaction` in other SDKs
* All functions have bang (`!`) variants that raise instead of returning error tuples.
* Parameters use snake\_case keys in the keyword list but are serialized to camelCase JSON keys.
* The proxy parameter is typed as an enum (`:basic`, `:enhanced`, `:auto`) — note that `:stealth` is not in the Elixir SDK's validated values.
* Additional Req options (custom headers, adapter config, etc.) can be passed through in the `opts` keyword list.

## Source Of Truth

* `firecrawl/apps/elixir-sdk/lib/firecrawl.ex`
* `firecrawl/apps/elixir-sdk/mix.exs`
* `firecrawl-docs/api-reference/v2-openapi.json`