> ## 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.

# Elixir Agent Quickstart

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

# Firecrawl Elixir Agent Quickstart

This file is the canonical quickstart for external agents integrating with Firecrawl via the official Elixir SDK. It is generated from SDK source and the OpenAPI spec. The Elixir SDK is auto-generated from the OpenAPI spec and uses function names that mirror operation IDs.

## Install

Add to your `mix.exs` dependencies:

```elixir theme={null}
defp deps do
  [
    {:firecrawl, "~> 1.12"}
  ]
end
```

## Authenticate

Configure in `config/config.exs`:

```elixir theme={null}
config :firecrawl, api_key: "fc-YOUR-API-KEY"
```

Or pass `api_key` as an option to any function call:

```elixir theme={null}
Firecrawl.search_and_scrape([query: "example"], api_key: "fc-YOUR-API-KEY")
```

## When To Use What

* **`search_and_scrape`** — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
* **`scrape_and_extract_from_url`** — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
* **`interact_with_scrape_browser_session`** / **`execute_browser_code`** — Use when a page needs browser automation — 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 function

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

### Example

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

for result <- response.body["data"]["web"] do
  IO.puts("#{result["title"]} #{result["url"]}")
end
```

### Parameters

All parameters are passed as a keyword list. Keys use snake\_case and are automatically mapped to camelCase for the API.

| Parameter | Type | Description |
| - | - | - |
| `query` | `:string` | The search query (max 500 chars). **Required.** |
| `limit` | `:integer` | Max results to return per source type. Default: `10` (API). Range: 1–100. |
| `sources` | `list` | Source types: `"web"`, `"news"`, `"images"`, `"alexandria"`. Default: `["web"]`. |
| `categories` | `list` | Filter by category: `"github"`, `"research"`, `"pdf"`, `"developer"`, `"gov"`. |
| `include_domains` | `list(string)` | Restrict results to these domains. Cannot combine with `exclude_domains`. |
| `exclude_domains` | `list(string)` | Exclude results from these domains. |
| `tbs` | `:string` | Time-based filter. E.g. `"qdr:d"` for past day, `"sbd:1,qdr:w"` for sorted by date in past week. |
| `location` | `:string` | Location for search results. |
| `country` | `:string` | ISO 3166-1 alpha-2 country code. |
| `highlights` | `:boolean` | Return query-relevant highlights. |
| `timeout` | `:integer` | Timeout in milliseconds. |
| `ignore_invalid_urls` | `:boolean` | Skip invalid URLs instead of failing. |
| `safe` | `:boolean` | Enable safe search. |
| `scrape_options` | `:keyword_list` | Apply scrape options to each result page. |
| `domain_tools` | `:boolean` | Include Alexandria tool contracts matched to result domains. |
| `tool_detail` | `:compact \| :summary \| :full` | Detail level for tool contracts. Default: `"compact"`. |
| `enterprise` | `list(string)` | Enterprise options: `"default"`, `"anon"`, `"zdr"`. |

### Bang variant

`Firecrawl.search_and_scrape!(params, opts)` — raises on error instead of returning `{:error, ...}`.

## 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 function

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

### Example

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

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

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `url` | `:string` | The URL to scrape. **Required.** |
| `formats` | `list` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, `"summary"`, `"audio"`, `"video"`, `"changeTracking"`, `"branding"`, `"product"`, `"menu"`. Default: `["markdown"]`. Some accept config maps. |
| `only_main_content` | `:boolean` | Strip headers, navs, footers. Default: `true` (API). |
| `only_clean_content` | `:boolean` | LLM-based boilerplate removal. Default: `false`. |
| `include_tags` | `list(string)` | Only include content from these HTML tags. |
| `exclude_tags` | `list(string)` | Exclude content from these HTML tags. |
| `headers` | `any` | Custom HTTP headers. |
| `wait_for` | `:integer` | Extra delay in ms before fetching content. Default: `0`. |
| `timeout` | `:integer` | Request timeout in ms. Default: 60000, max: 300000. |
| `mobile` | `:boolean` | Emulate a mobile device. Default: `false`. |
| `max_age` | `:integer` | Use cached result if younger than this (ms). Default: 172800000 (2 days). |
| `min_age` | `:integer` | Cache-only mode. |
| `store_in_cache` | `:boolean` | Cache this scrape result. |
| `actions` | `list` | Browser actions before scraping. |
| `location` | `:keyword_list` | Geolocation config. |
| `parsers` | `list` | File parsers. Default: `["pdf"]`. |
| `proxy` | `:basic \| :enhanced \| :auto \| string` | Proxy type. |
| `skip_tls_verification` | `:boolean` | Skip TLS verification. Default: `true` (API). |
| `remove_base64_images` | `:boolean` | Strip base64 images from output. |
| `block_ads` | `:boolean` | Block ads and cookie popups. |
| `lockdown` | `:boolean` | Serve only cached results. |
| `check_prompt_injection` | `:boolean` | Scan for prompt injection (adds 4 credits). |
| `redact_pii` | `any` | Redact PII. |
| `profile` | `:keyword_list` | Persistent browser profile. |
| `zero_data_retention` | `:boolean` | Enable zero data retention. |
| `alexandria` | `any` | Alexandria tool execution. |
| `domain_tools` | `:boolean` | Return Alexandria tool contracts. |

### Bang variant

`Firecrawl.scrape_and_extract_from_url!(params, opts)` — raises on error.

## Interact

### Why use it

The Elixir SDK supports two interact patterns:

1. **Post-scrape interaction** — After scraping a page, interact with its browser session using `interact_with_scrape_browser_session/3`.
2. **Standalone browser session** — Create an independent browser session with `create_browser_session/2`, then execute code with `execute_browser_code/3`.

### Preferred SDK functions

**Post-scrape interaction:**

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

**Standalone browser session:**

```
Firecrawl.create_browser_session(params, opts \\ [])
Firecrawl.execute_browser_code(session_id, params, opts \\ [])
```

### Example — Post-scrape interaction

```elixir theme={null}
{:ok, scrape} = Firecrawl.scrape_and_extract_from_url(url: "https://example.com")
scrape_id = scrape.body["data"]["metadata"]["scrapeId"]

{:ok, response} = Firecrawl.interact_with_scrape_browser_session(scrape_id,
  code: "document.title",
  language: :node
)

IO.puts(response.body["data"]["result"])

Firecrawl.stop_interactive_scrape_browser_session(scrape_id)
```

### Example — Standalone browser session

```elixir theme={null}
{:ok, session} = Firecrawl.create_browser_session(ttl: 300)
session_id = session.body["data"]["sessionId"]

{:ok, response} = Firecrawl.execute_browser_code(session_id,
  code: ~s(await page.goto("https://example.com"); document.title),
  language: :node
)

IO.puts(response.body["data"]["result"])

Firecrawl.delete_browser_session(session_id)
```

### Post-scrape interaction parameters

| Parameter | Type | Description |
| - | - | - |
| `job_id` | `String.t()` | The scrape job ID from a previous scrape. **Required (positional).** |
| `code` | `:string` | Code to execute in the browser sandbox. **Required.** Max 100,000 chars. |
| `language` | `:python \| :node \| :bash` | Language for code execution. Default: `"node"` (API). |
| `timeout` | `:integer` | Execution timeout in seconds. Min: 1, default: 30 (API), max: 300. |
| `origin` | `:string` | Origin label for telemetry. |

### Standalone browser session parameters

**`create_browser_session`:**

| Parameter | Type | Description |
| - | - | - |
| `ttl` | `:integer` | Total session TTL in seconds. Default: 300. Range: 30–3600. |
| `activity_ttl` | `:integer` | Inactivity timeout in seconds. Range: 10–3600. |
| `stream_web_view` | `:boolean` | Stream a live browser view. Default: `true`. |
| `block_ads` | `:boolean` | Block ads and cookie popups. Default: `true`. |
| `profile` | `:keyword_list` | Persistent storage profile. |
| `location` | `:keyword_list` | Country: `[country: "GB"]`. |

**`execute_browser_code`:**

| Parameter | Type | Description |
| - | - | - |
| `session_id` | `String.t()` | The session ID. **Required (positional).** |
| `code` | `:string` | Code to execute. **Required.** |
| `language` | `:python \| :node \| :bash` | Language. Default: `"node"` (API). |
| `timeout` | `:integer` | Timeout in seconds. |

### Stopping sessions

* Post-scrape: `Firecrawl.stop_interactive_scrape_browser_session(job_id)`
* Standalone: `Firecrawl.delete_browser_session(session_id)`

## Notes

* **No deprecated aliases** exist in the Elixir SDK.
* **Naming style:** All parameters use snake\_case. The SDK auto-maps to camelCase for the API.
* **Function names are OpenAPI-derived.** They mirror operation IDs exactly (e.g. `scrape_and_extract_from_url`, not `scrape`).
* **Return type:** All functions return `{:ok, Req.Response.t()} | {:error, Exception.t()}`. Use bang variants (`!`) to raise on error.
* **Package name:** `:firecrawl` (Hex.pm).
* **Base URL:** Defaults to `https://api.firecrawl.dev/v2`. Override with `base_url` option.
* **Dependencies:** `req ~> 0.5`, `nimble_options ~> 1.1`.

## 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.