> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-rl7tly.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 Firecrawl via the Elixir SDK. It is generated from SDK source (`apps/elixir-sdk`) plus the OpenAPI spec (`api-reference/v2-openapi.json`). The Elixir SDK is auto-generated from the OpenAPI spec. Function names are verbose and OpenAPI-shaped — use them exactly as shown. ## Install Add `firecrawl` to your `mix.exs`: ```elixir theme={null} defp deps do [ {:firecrawl, "~> 1.0"} ] end ``` Then run: ```bash theme={null} mix deps.get ``` ## Authenticate Configure your API key in `config/config.exs`: ```elixir theme={null} config :firecrawl, api_key: System.get_env("FIRECRAWL_API_KEY") ``` Or pass it per-request: ```elixir theme={null} Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR-API-KEY") ``` All functions accept a trailing `opts` keyword list supporting: | Option | Type | Default | Description | | ----------- | -------- | ----------------------------------------- | ------------------------------------------------- | | `:api_key` | `string` | Application config `:firecrawl, :api_key` | Override the API key. Omit for keyless free tier. | | `:base_url` | `string` | `"https://api.firecrawl.dev/v2"` | Override for self-hosted instances. | ## When To Use What * **`search_and_scrape`** — Use when you start with a query and need to discover relevant pages. * **`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 code execution in a post-scrape browser session. ## Search ### Why use it Search the web with a query and get structured results. Each result can optionally include full scraped page content. ### Preferred SDK function ``` Firecrawl.search_and_scrape(params, opts \\ []) Firecrawl.search_and_scrape!(params, opts \\ []) # bang variant, raises on error ``` ### Example ```elixir theme={null} {:ok, result} = Firecrawl.search_and_scrape(query: "firecrawl web scraping", limit: 5) for entry <- result.body["data"]["web"] do IO.puts("#{entry["title"]} - #{entry["url"]}") end ``` ### Parameters Pass as a keyword list. All parameters use `snake_case` keys; the SDK converts to camelCase for the API. | Parameter | Type | Required | Description | | ---------------------- | -------------- | -------- | --------------------------------------------------------------------------------- | | `:query` | `string` | **yes** | The search query. | | `:sources` | `list(any)` | no | Sources to search. Server default: `["web"]`. | | `:categories` | `list(any)` | no | Category filters for results. | | `:include_domains` | `list(string)` | no | Only include results from these domains. | | `:exclude_domains` | `list(string)` | no | Exclude results from these domains. | | `:limit` | `integer` | no | Max number of results. | | `:tbs` | `string` | no | Time-based search filter (e.g. `"qdr:d"` for past day). | | `:location` | `string` | no | Geographic location for results. | | `:country` | `string` | no | ISO country code for geo-targeting. | | `:ignore_invalid_urls` | `boolean` | no | Exclude invalid URLs from results. | | `:timeout` | `integer` | no | Timeout in milliseconds. | | `:highlights` | `boolean` | no | Generate query-relevant highlights. Server default: `true`. | | `:scrape_options` | `keyword` | no | Options applied when scraping each result. | | `:enterprise` | `list(string)` | no | Enterprise options: `["zdr"]` for Zero Data Retention, `["anon"]` for anonymized. | ### Response Returns `{:ok, %Req.Response{}}` or `{:error, exception}`. Access data via `result.body["data"]`. ## Scrape ### Why use it Fetch a single URL and get back clean content in your chosen formats: markdown, HTML, screenshots, structured JSON extraction, and more. ### Preferred SDK function ``` Firecrawl.scrape_and_extract_from_url(params, opts \\ []) Firecrawl.scrape_and_extract_from_url!(params, opts \\ []) # bang variant ``` ### Example ```elixir theme={null} {:ok, result} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com", formats: ["markdown", "links"] ) IO.puts(result.body["data"]["markdown"]) ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------ | ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `:url` | `string` | **yes** | The URL to scrape. | | `:formats` | `list(any)` | no | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, `"audio"`, `"video"`, etc. | | `:headers` | `any` | no | Custom HTTP headers (cookies, user-agent). | | `:include_tags` | `list(string)` | no | HTML tags to include. | | `:exclude_tags` | `list(string)` | no | HTML tags to exclude. | | `:only_main_content` | `boolean` | no | Strip navbars, footers, sidebars. | | `:timeout` | `integer` | no | Timeout in ms. Default: `60000`, max: `300000`. | | `:wait_for` | `integer` | no | Delay in ms before fetching content. | | `:mobile` | `boolean` | no | Emulate a mobile device. | | `:parsers` | `list(any)` | no | File parser config (e.g. PDF). | | `:actions` | `list(any)` | no | Browser actions before extraction. | | `:location` | `keyword` | no | Location settings for proxy/language. | | `:skip_tls_verification` | `boolean` | no | Skip TLS certificate verification. | | `:remove_base64_images` | `boolean` | no | Remove base64 images from markdown. | | `:block_ads` | `boolean` | no | Block ads and cookie popups. | | `:proxy` | `:basic \| :enhanced \| :auto` | no | Proxy routing mode. | | `:max_age` | `integer` | no | Max cache age in ms. | | `:min_age` | `integer` | no | Min cache age in ms for cache-only mode. | | `:store_in_cache` | `boolean` | no | Store result in cache. | | `:lockdown` | `boolean` | no | Only serve cached results. | | `:redact_pii` | `boolean` | no | Redact PII. | | `:profile` | `keyword` | no | Persistent browser profile (`:name`, `:save_changes`). | | `:audit_metadata` | `keyword` | no | SIEM audit attribution (`:username`). | ## Interact ### Why use it After scraping a page, use `interact_with_scrape_browser_session` to execute code in the live browser session: run Playwright scripts in Node.js, Python, or Bash. ### Preferred SDK function ``` Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ []) Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts \\ []) # bang variant ``` Stop the session when done: ``` Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ []) Firecrawl.stop_interactive_scrape_browser_session!(job_id, opts \\ []) ``` ### Example ```elixir theme={null} {:ok, scrape} = Firecrawl.scrape_and_extract_from_url( url: "https://www.amazon.com", formats: ["markdown"] ) scrape_id = get_in(scrape.body, ["data", "metadata", "scrapeId"]) {:ok, run} = Firecrawl.interact_with_scrape_browser_session( scrape_id, code: ~s|const title = await page.title(); console.log(title);|, language: :node ) IO.inspect(run.body) Firecrawl.stop_interactive_scrape_browser_session(scrape_id) ``` ### Parameters | Parameter | Type | Required | Description | | ----------- | --------------------------- | -------- | -------------------------------------------------------------- | | `job_id` | `String.t()` | **yes** | **(first arg)** The `scrapeId` from a prior scrape's metadata. | | `:code` | `string` | **yes** | Code to execute in the browser sandbox. | | `:language` | `:python \| :node \| :bash` | no | Language of the code. Use `:node` for JavaScript. | | `:timeout` | `integer` | no | Execution timeout in seconds. | | `:origin` | `string` | no | Request attribution label. | ### Interact limitation: no `prompt` support The Elixir SDK's `interact_with_scrape_browser_session` requires `code` — it does not currently support the `prompt` parameter for natural-language browser interaction. For prompt-based interaction, use the REST API directly: ```elixir theme={null} headers = [ {"Authorization", "Bearer #{Application.get_env(:firecrawl, :api_key)}"}, {"Content-Type", "application/json"} ] {:ok, response} = Req.post( "https://api.firecrawl.dev/v2/scrape/#{scrape_id}/interact", json: %{prompt: "Search for iPhone 16 Pro Max"}, headers: headers ) IO.inspect(response.body) ``` ## Notes * **Function names**: The Elixir SDK is auto-generated from the OpenAPI spec. Function names are verbose (e.g. `scrape_and_extract_from_url`, `search_and_scrape`, `interact_with_scrape_browser_session`). Use them exactly as documented. * **Naming**: Parameters use `snake_case` keys in keyword lists. The SDK converts to camelCase for the API. * **Bang variants**: Every function has a `!` bang variant that raises on error instead of returning `{:error, ...}`. * **Return type**: Non-bang functions return `{:ok, %Req.Response{}}` or `{:error, exception}`. Access response data via `result.body["data"]`. * **Interact `prompt`**: Not supported in the SDK. Use raw `Req.post` to the REST API for prompt-based interaction. ## Source Of Truth * `firecrawl/apps/elixir-sdk/mix.exs` * `firecrawl/apps/elixir-sdk/lib/firecrawl.ex` * `firecrawl-docs/api-reference/v2-openapi.json`