> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-4orfll.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 using the Elixir SDK. It is generated from SDK source and OpenAPI spec. ## Install Add to your `mix.exs` dependencies: ```elixir theme={null} {:firecrawl, "~> 1.10"} ``` Then run: ```bash theme={null} mix deps.get ``` ## Authenticate Set the API key in application config: ```elixir theme={null} config :firecrawl, api_key: "fc-YOUR_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") ``` Omitting the key uses the keyless free tier (rate-limited per IP). **Per-request options (second keyword list):** | Option | Type | Default | Description | | ---------- | -------- | -------------------------------- | --------------------------------- | | `api_key` | `string` | Application config or `nil` | API key override for this request | | `base_url` | `string` | `"https://api.firecrawl.dev/v2"` | Base URL override | ## When To Use What * **`search_and_scrape`**: Use when you start with a query and need to discover relevant pages. Returns ranked results with optional scraping. * **`scrape_and_extract_from_url`**: Use when you already have a URL and want its content in markdown, HTML, JSON, or other formats. * **`interact_with_scrape_browser_session`**: Use when a page needs post-scrape browser actions — clicking, filling forms, running code in the browser sandbox. ## Search ### Why use it Search the web for a query and get back ranked results. Optionally scrape each result page inline by passing `scrape_options`. ### Preferred SDK method ```elixir theme={null} Firecrawl.search_and_scrape(params, opts \\ []) ``` Bang variant `search_and_scrape!/2` raises on error. ### Example ```elixir theme={null} {:ok, response} = Firecrawl.search_and_scrape( query: "firecrawl web scraping API", limit: 5, scrape_options: [formats: ["markdown"]] ) for item <- response.body["data"]["web"] || [] do IO.puts("#{item["title"]} #{item["url"]}") end ``` ### Parameters All parameters are passed as a keyword list. All are optional except `query`. | Parameter | Type | Description | | --------------------- | ------------------ | ------------------------------------------------------- | | `query` | `:string` | **Required.** The search query. | | `limit` | `:integer` | Max results to return. | | `sources` | `{:list, :any}` | Sources: `"web"`, `"news"`, `"images"`. | | `categories` | `{:list, :any}` | Filter: `"github"`, `"research"`, `"pdf"`. | | `include_domains` | `{:list, :string}` | Restrict results to these domains. | | `exclude_domains` | `{:list, :string}` | Exclude results from these domains. | | `tbs` | `:string` | Time-based search filter (e.g. `"qdr:d"` for past day). | | `location` | `:string` | Location string for geo-targeted results. | | `country` | `:string` | ISO country code for geo-targeting (e.g. `"US"`). | | `ignore_invalid_urls` | `:boolean` | Ignore invalid URLs in results. | | `timeout` | `:integer` | Timeout in milliseconds. | | `highlights` | `:boolean` | Generate query-relevant highlights. Default: `true`. | | `scrape_options` | `:keyword_list` | Scrape options applied to each result page. | | `enterprise` | `{:list, :string}` | Enterprise options: `["zdr"]` or `["anon"]`. | **Returns:** `{:ok, Req.Response.t()}` or `{:error, Exception.t()}`. The response body contains `"data"` with `"web"`, `"news"`, and `"images"` lists. ## Scrape ### Why use it Scrape a single URL and get its content as markdown, HTML, structured JSON, screenshots, or other formats. ### Preferred SDK method ```elixir theme={null} Firecrawl.scrape_and_extract_from_url(params, opts \\ []) ``` Bang variant `scrape_and_extract_from_url!/2` raises on error. ### 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 All parameters are passed as a keyword list. All are optional except `url`. | Parameter | Type | Description | | ----------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `:string` | **Required.** The URL to scrape. | | `formats` | `{:list, :any}` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. | | `only_main_content` | `:boolean` | Extract only the main content, excluding headers/navs/footers. | | `include_tags` | `{:list, :string}` | HTML tags to include in output. | | `exclude_tags` | `{:list, :string}` | HTML tags to exclude from output. | | `timeout` | `:integer` | Timeout in milliseconds (default 60000, max 300000). | | `wait_for` | `:integer` | Delay in ms before fetching content. | | `mobile` | `:boolean` | Emulate a mobile device. | | `headers` | `:any` | Custom HTTP headers. | | `actions` | `{:list, :any}` | Browser actions before scraping. | | `parsers` | `{:list, :any}` | Parser configs (e.g. `"pdf"`). | | `location` | `:keyword_list` | Geo-location with `country` and `languages` fields. | | `skip_tls_verification` | `:boolean` | Skip TLS certificate verification. | | `remove_base64_images` | `:boolean` | Remove base64 images from output. | | `block_ads` | `:boolean` | Block ads and cookie popups. | | `proxy` | `:basic \| :enhanced \| :auto` | Proxy tier. | | `max_age` | `:integer` | Use cached result if younger than this (ms). | | `min_age` | `:integer` | Min age for cache-only check (ms). | | `store_in_cache` | `:boolean` | Store result in Firecrawl cache. | | `lockdown` | `:boolean` | Serve from cache only. | | `redact_pii` | `:boolean` | Redact PII from returned content. | | `audit_metadata` | `:keyword_list` | User attribution for SIEM logging (requires `username`). | | `profile` | `:keyword_list` | Persistent browser profile. | **Returns:** `{:ok, Req.Response.t()}` or `{:error, Exception.t()}`. The response body contains `"data"` with `"markdown"`, `"html"`, `"links"`, `"metadata"`, etc. ## Interact ### Why use it Execute code in the browser session of a previous scrape job. Use this for clicking buttons, filling forms, navigating multi-step flows, or running arbitrary JavaScript/Python/Bash in the browser sandbox. ### Preferred SDK method ```elixir theme={null} Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ []) ``` Bang variant `interact_with_scrape_browser_session!/3` 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"]["jobId"] {:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id, code: "document.querySelector('button.load-more').click();", language: :node, timeout: 30 ) IO.puts(result.body["stdout"]) ``` ### Parameters | Parameter | Type | Description | | ---------- | --------------------------- | ------------------------------------------------------------ | | `job_id` | `String.t()` | **Required.** The scrape job ID (first positional argument). | | `code` | `:string` | **Required.** Code to execute in the browser sandbox. | | `language` | `:python \| :node \| :bash` | Execution language. Default: `:node`. | | `timeout` | `:integer` | Execution timeout in seconds (1–300). | **Returns:** `{:ok, Req.Response.t()}` with body containing `"success"`, `"stdout"`, `"stderr"`, `"result"`, `"exitCode"`, `"killed"`, `"error"`. **Stop the session:** ```elixir theme={null} Firecrawl.stop_interactive_scrape_browser_session(job_id) ``` ## Notes * All parameter names use **snake\_case** (e.g. `only_main_content`, `skip_tls_verification`). The SDK converts them to camelCase JSON keys internally. * Parameters are passed as **keyword lists**, not maps. * The SDK is **auto-generated from the OpenAPI spec**. Function names match the OpenAPI operation IDs closely. * The `interact_with_scrape_browser_session` function only supports `code`, not `prompt` (natural-language browser instruction). Use `code` to execute scripts directly. * Proxy values are atoms (`:basic`, `:enhanced`, `:auto`), not strings. * Every function has a bang variant (`!`) that raises instead of returning `{:error, ...}`. * There are **no deprecated aliases** in the Elixir SDK. ## Source Of Truth * `firecrawl/apps/elixir-sdk/lib/firecrawl.ex` * `firecrawl/apps/elixir-sdk/mix.exs` * `firecrawl-docs/api-reference/v2-openapi.json`