> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-uhqa26.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` v1.11.0) and the v2 OpenAPI spec.

## Install

Add to `mix.exs`:

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

## Authenticate

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

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

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

## Search

### Why use it

Discover relevant pages from a query, then pick URLs to scrape or interact with. Use `site:example.com` to limit results to a domain.

### 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")

{:ok, res} = Firecrawl.search_and_scrape(
  query: "site:docs.firecrawl.dev crawl webhooks",
  sources: [:web, :news],
  categories: [:research],
  limit: 10,
  tbs: "qdr:m",
  location: "San Francisco,California,United States",
  scrape_options: [
    formats: ["markdown", "links"],
    only_main_content: true
  ]
)
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | string | Search query. Use `site:example.com` to limit to a domain. |
| `sources` | list | Sources to search: `:web`, `:news`, `:images` (or string equivalents). |
| `categories` | list | Filter by category: `:developer`, `:research`, `:pdf` (or string equivalents). |
| `exclude_domains` | list | Exclude results from these domains. |
| `limit` | integer | Cap the number of results. |
| `tbs` | string | Time-based filter (e.g. `qdr:d` for past day). |
| `location` | string | Localized results. |
| `country` | string | ISO 3166-1 alpha-2 country code. |
| `ignore_invalid_urls` | boolean | Drop URLs that cannot be scraped. |
| `timeout` | integer | Request timeout in milliseconds. |
| `highlights` | boolean | Include highlights in results. |
| `scrape_options` | keyword list | Scrape each search result. See Scrape parameters. |
| `enterprise` | list | Enterprise controls: `"zdr"`, `"anon"`. |

## Scrape

### Why use it

Fetch 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://docs.firecrawl.dev",
  formats: ["markdown"]
)

{:ok, res} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com/pricing",
  formats: [
    "markdown",
    "links",
    %{type: "json", prompt: "Extract plan names and prices."},
    %{type: "screenshot", fullPage: true}
  ],
  only_main_content: true,
  wait_for: 1000,
  actions: [
    %{type: "click", selector: "#accept"},
    %{type: "wait", milliseconds: 750},
    %{type: "scrape"}
  ]
)
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `url` | string | URL to scrape. |
| `formats` | list | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`. Use maps for object formats. |
| `headers` | map | Custom request headers. |
| `include_tags` | list | Include only specific HTML tags. |
| `exclude_tags` | list | Exclude specific HTML tags. |
| `only_main_content` | boolean | Strip nav, footer, and boilerplate. |
| `timeout` | integer | Timeout in milliseconds. |
| `wait_for` | integer | Wait for page to render (milliseconds). |
| `mobile` | boolean | Use a mobile viewport. |
| `parsers` | list | File parsing controls (e.g. `"pdf"` or `%{type: "pdf", mode: "auto", maxPages: 5}`). |
| `actions` | list | Pre-scrape browser actions (maps with `type` key). |
| `location` | keyword list | Geo/language-aware scraping (`country:`, `languages:`). |
| `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 control: `:basic`, `:enhanced`, `:auto`. |
| `max_age` | integer | Cached data max age (milliseconds). |
| `min_age` | integer | Cached data minimum age (milliseconds). |
| `store_in_cache` | boolean | Cache the result. |
| `lockdown` | boolean | Serve only cached content. |
| `redact_pii` | boolean | Redact personally identifiable information. |
| `profile` | keyword list | Persistent browser profile (`name:`, `save_changes:`). |
| `zero_data_retention` | boolean | Zero data retention for this scrape. |
| `audit_metadata` | map or keyword list | SIEM audit logging metadata. |

## Interact

### Why use it

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

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

{: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 (required). |
| `language` | atom or string | Runtime: `:python`, `:node`, `:bash`. |
| `timeout` | integer | Execution timeout in seconds. |
| `origin` | string | Optional origin label for telemetry. |

## Notes

* The Elixir client is OpenAPI-shaped; function names are generated from the spec.
* Each function has a bang (`!`) variant that raises on error instead of returning `{:error, _}`.
* This SDK exposes code-based interactions only (no `prompt` parameter on interact).
* Dependencies: `req ~> 0.5`, `nimble_options ~> 1.1`.

## Source Of Truth

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


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