> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-iq666a.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 `firecrawl` hex package source (v1.11.3) and the v2 OpenAPI spec. Function names and parameters match the SDK public API.

## Install

Add to `mix.exs`:

```elixir theme={null}
{:firecrawl, "~> 1.11"}
```

## Authenticate

```elixir theme={null}
# config/runtime.exs or config.exs
config :firecrawl, api_key: System.get_env("FIRECRAWL_API_KEY")

# or pass api_key per call
{:ok, res} = Firecrawl.search_and_scrape(
  [query: "site:docs.firecrawl.dev webhook retries"],
  api_key: "fc-your-api-key"
)
```

## When To Use What

* **`search`**: use when you start with a query and need discovery. Returns matching pages you can then scrape.
* **`scrape`**: use when you already have a URL and want page content in markdown, HTML, JSON, or other formats.
* **`interact`**: use when the page needs clicks, forms, or post-scrape browser actions.

## 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:`, e.g. `site:docs.firecrawl.dev crawl webhooks`.

### Preferred SDK method

`Firecrawl.search_and_scrape(params \\ [], opts \\ [])`

### Example

```elixir theme={null}
{:ok, res} = Firecrawl.search_and_scrape(
  query: "site:docs.firecrawl.dev webhook retries",
  limit: 5
)
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Search query. Use `site:example.com` to limit to a domain. |
| `sources` | list | Sources: `"web"`, `"news"`, `"images"`, `:web`, `:news`, `:images`. Also accepts maps like `%{type: "web"}`. |
| `categories` | list | Filter: `"developer"`, `"research"`, `"pdf"`, or atom equivalents. Also accepts maps. |
| `include_domains` | list of strings | Restrict results to these domains. |
| `exclude_domains` | list of strings | Exclude results from these domains. |
| `limit` | integer | Cap result count. |
| `tbs` | string | Time-based filter, e.g. `"qdr:d"`. |
| `location` | string | Localized results. |
| `country` | string | ISO country code for geo-targeted results. |
| `ignore_invalid_urls` | boolean | Drop URLs that can't be scraped. |
| `highlights` | boolean | Generate query-relevant highlights. |
| `timeout` | integer | Request timeout in milliseconds. |
| `scrape_options` | keyword list | Scrape each result (same fields as scrape params). |
| `domain_tools` | boolean | Include Alexandria domain-matched tools. |
| `tool_detail` | atom or string | Detail level: `:compact`, `:summary`, `:full`. |
| `enterprise` | list of strings | Enterprise options: `["zdr"]` for Zero Data Retention, `["anon"]` for anonymized. |

## Scrape

### Why use it

Get structured content from a URL in one or more formats.

### Preferred SDK method

`Firecrawl.scrape_and_extract_from_url(params \\ [], opts \\ [])`

### Example

```elixir theme={null}
{:ok, res} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com/pricing",
  formats: [
    "markdown",
    %{type: "json", prompt: "Extract plan names and prices."}
  ],
  only_main_content: true
)
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `url` | string | Page URL to scrape. |
| `formats` | list | Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`. Maps: `%{type: "json", prompt: ..., schema: ...}`, `%{type: "screenshot", fullPage: true}`, etc. |
| `headers` | map | Custom request headers. |
| `include_tags` | list of strings | Include only these HTML tags. |
| `exclude_tags` | list of strings | Exclude these HTML tags. |
| `only_main_content` | boolean | Strip nav, footer, boilerplate. |
| `timeout` | integer | Timeout in milliseconds. |
| `wait_for` | integer | Wait for page render (milliseconds). |
| `mobile` | boolean | Use mobile viewport. |
| `parsers` | list | File parsing, e.g. `[%{type: "pdf", mode: "auto", maxPages: 5}]`. |
| `actions` | list of maps | Pre-scrape browser actions: `click`, `wait`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`. |
| `location` | keyword list | Geo/language: `[country: "US", languages: ["en-US"]]`. |
| `skip_tls_verification` | boolean | Skip TLS verification. |
| `remove_base64_images` | boolean | Drop base64 images from markdown. |
| `block_ads` | boolean | Block ads and cookie popups. |
| `proxy` | atom or string | Proxy: `:basic`, `:enhanced`, `:auto`. |
| `max_age` | integer | Accept cached data up to this age (ms). |
| `min_age` | integer | Accept cached data only if at least this old (ms). |
| `store_in_cache` | boolean | Cache the result. |
| `lockdown` | boolean | Serve only cached results. |
| `profile` | keyword list | Persistent browser profile: `[name: "my-session", save_changes: true]`. |
| `zero_data_retention` | boolean | Enable zero data retention. |
| `domain_tools` | boolean | Include Alexandria domain-matched tools. |

## Interact

### Why use it

Control the browser session tied to a scrape job. The Elixir SDK supports code-based interactions (no `prompt` parameter on the scrape-bound interact).

### Preferred SDK method

`Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ [])`

### Example

```elixir theme={null}
{:ok, res} = Firecrawl.interact_with_scrape_browser_session(
  "<scrapeJobId>",
  code: "console.log(await page.title());",
  language: :node,
  timeout: 60
)

# End the session when done:
{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session("<scrapeJobId>")
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `job_id` | string | Scrape job ID. |
| `code` | string | Code to run in the browser session. |
| `language` | atom or string | Runtime: `:python`, `:node`, `:bash`. |
| `timeout` | integer | Execution timeout in seconds. |

**Stop session**: `Firecrawl.stop_interactive_scrape_browser_session(job_id)` ends the browser session.

### Standalone interact sessions

The Elixir SDK also exposes standalone interact sessions (not tied to a scrape):

* `Firecrawl.create_browser_session(params, opts)` — create a standalone session with `ttl`, `activity_ttl`, `stream_web_view`, `profile`.
* `Firecrawl.execute_browser_code(session_id, params, opts)` — execute code with `code`, `language`, `timeout`.
* `Firecrawl.delete_browser_session(session_id, opts)` — destroy the session.
* `Firecrawl.list_browser_sessions(params, opts)` — list sessions, optionally filtered by `status` (`:active`, `:destroyed`).

## Notes

* The Elixir client is auto-generated from the OpenAPI spec. Function names are OpenAPI operation IDs converted to snake\_case.
* Every function has a bang (`!`) variant that raises on error instead of returning `{:error, _}`.
* Snake\_case params are automatically converted to camelCase for the JSON API body.
* This SDK exposes code-based interactions only on the scrape-bound endpoint (no `prompt` parameter on `interact_with_scrape_browser_session`).

## Source Of Truth

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


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