> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-zges5p.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 the OpenAPI spec. ## Install Add to your `mix.exs` dependencies: ```elixir theme={null} {:firecrawl, "~> 1.10"} ``` Then run: ```bash theme={null} mix deps.get ``` ## Authenticate Pass the API key as a runtime option on each call: ```elixir theme={null} opts = [api_key: "fc-YOUR_API_KEY"] ``` To use a self-hosted instance: ```elixir theme={null} opts = [api_key: "fc-YOUR_API_KEY", base_url: "https://your-instance.com"] ``` ## When To Use What * **`search_and_scrape`**: Use when you start with a query and need to discover relevant pages across the web. * **`scrape_and_extract_from_url`**: Use when you already have a URL and want its content (markdown, HTML, structured data, screenshots, etc.). * **`interact_with_scrape_browser_session`**: Use when a page needs post-scrape browser actions — clicking, filling forms, executing code in a live browser session. ## Search ### Why use it Search the web for a query and optionally scrape each result in one call. Returns results grouped by source type (web, news, images). ### Preferred SDK function ```elixir theme={null} Firecrawl.search_and_scrape(params, opts) Firecrawl.search_and_scrape!(params, opts) ``` The bang variant (`!`) raises on error instead of returning `{:error, ...}`. ### Example ```elixir theme={null} {:ok, response} = Firecrawl.search_and_scrape( [ query: "firecrawl web scraping API", limit: 5, scrape_options: [formats: ["markdown"]] ], api_key: "fc-YOUR_API_KEY" ) IO.inspect(response.body) ``` ### Parameters Parameters are a keyword list (first argument). | Parameter | Type | Required | Description | | --------------------- | ------------------ | -------- | --------------------------------------------------------------------- | | `query` | `:string` | **Yes** | The search query string. | | `sources` | `{:list, :any}` | No | Sources to search: `"web"`, `"news"`, `"images"`. Default: `["web"]`. | | `categories` | `{:list, :any}` | No | Filter results: `"github"`, `"research"`, `"pdf"`, `"developer"`. | | `include_domains` | `{:list, :string}` | No | Restrict results to these domains. | | `exclude_domains` | `{:list, :string}` | No | Exclude results from these domains. | | `limit` | `:integer` | No | Max results per source type. Default: `10`. Max: `100`. | | `tbs` | `:string` | No | Time-based search filter (e.g. `"qdr:d"` for past day). | | `location` | `:string` | No | Geographic location string. | | `country` | `:string` | No | ISO country code for geo-targeting. | | `ignore_invalid_urls` | `:boolean` | No | Exclude invalid URLs from results. Default: `false`. | | `timeout` | `:integer` | No | Timeout in milliseconds. Default: `60000`. | | `highlights` | `:boolean` | No | Generate query-relevant highlights. Default: `true`. | | `scrape_options` | `:keyword_list` | No | Options applied when scraping each result. | | `enterprise` | `{:list, :string}` | No | Enterprise ZDR options. | ### Return type `{:ok, %Req.Response{}}` or `{:error, exception}`. The response body contains `"data"` with `"web"`, `"news"`, `"images"` arrays. ## Scrape ### Why use it Scrape a single URL and get back clean markdown, HTML, structured JSON, screenshots, or other formats. Supports browser actions, location targeting, and caching. ### Preferred SDK function ```elixir theme={null} Firecrawl.scrape_and_extract_from_url(params, opts) 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"] ], api_key: "fc-YOUR_API_KEY" ) data = response.body["data"] IO.puts(data["markdown"]) ``` ### Parameters Parameters are a keyword list (first argument). | Parameter | Type | Required | Description | | ----------------------- | ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `:string` | **Yes** | The URL to scrape. | | `formats` | `{:list, :any}` | No | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or maps with format-specific options. Default: `["markdown"]`. | | `only_main_content` | `:boolean` | No | Extract main content only. Default: `true`. | | `include_tags` | `{:list, :string}` | No | HTML tags to include. | | `exclude_tags` | `{:list, :string}` | No | HTML tags to exclude. | | `headers` | `:any` | No | Custom HTTP headers. | | `timeout` | `:integer` | No | Timeout in milliseconds. Default: `60000`. | | `wait_for` | `:integer` | No | Extra delay in ms before fetching content. Default: `0`. | | `mobile` | `:boolean` | No | Emulate a mobile device. Default: `false`. | | `actions` | `{:list, :any}` | No | Browser actions: wait, click, write, press, scroll, screenshot, scrape, executeJavascript, pdf. | | `location` | `:keyword_list` | No | Location targeting with `country` and `languages`. | | `skip_tls_verification` | `:boolean` | No | Skip TLS verification. Default: `true`. | | `remove_base64_images` | `:boolean` | No | Remove base64 images from markdown. Default: `true`. | | `block_ads` | `:boolean` | No | Block ads and cookie popups. Default: `true`. | | `proxy` | `:basic \| :enhanced \| :auto` | No | Proxy type. Default: `"auto"`. | | `max_age` | `:integer` | No | Cache max age in milliseconds. Default: `172800000` (2 days). | | `min_age` | `:integer` | No | Cache-only: minimum cache age in ms. | | `store_in_cache` | `:boolean` | No | Store result in cache. Default: `true`. | | `lockdown` | `:boolean` | No | Cache-only mode. Default: `false`. | | `parsers` | `{:list, :any}` | No | File parser configs. Default: `["pdf"]`. | | `redact_pii` | `:boolean` | No | Redact PII from markdown. Default: `false`. | | `profile` | `:keyword_list` | No | Persistent browser profile. | | `audit_metadata` | `:keyword_list` | No | User attribution for SIEM logging (requires `username`). | | `zero_data_retention` | `:boolean` | No | Enable zero data retention for this scrape. | ### Return type `{:ok, %Req.Response{}}` or `{:error, exception}`. The response body `"data"` contains the scraped document fields. ## Interact ### Why use it Run code in the live browser session of an existing scrape job. Use it for clicks, form fills, navigation, or any post-scrape browser automation. ### Preferred SDK function ```elixir theme={null} Firecrawl.interact_with_scrape_browser_session(job_id, params, opts) Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts) ``` ### Example ```elixir theme={null} # First, scrape a page to get a job ID {:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url( [url: "https://example.com"], api_key: "fc-YOUR_API_KEY" ) job_id = scrape_response.body["data"]["metadata"]["scrapeId"] # Then interact with the browser session {:ok, response} = Firecrawl.interact_with_scrape_browser_session( job_id, [ code: ~s|document.querySelector("button.submit").click();|, language: :node ], api_key: "fc-YOUR_API_KEY" ) IO.inspect(response.body) ``` ### Parameters | Parameter | Type | Required | Description | | ---------- | --------------------------- | -------- | ------------------------------------------------------------------ | | `job_id` | `String.t()` | **Yes** | The scrape job ID (path parameter). | | `code` | `:string` | **Yes** | Code to execute in the browser sandbox. | | `language` | `:python \| :node \| :bash` | No | Runtime language. Default: `"node"`. | | `timeout` | `:integer` | No | Execution timeout in seconds. Default: `30`. Min: `1`, Max: `300`. | | `origin` | `:string` | No | Origin label for execution telemetry. | ### Return type `{:ok, %Req.Response{}}` or `{:error, exception}`. The response body contains `.success`, `.stdout`, `.result`, `.stderr`, `.exitCode`, `.error`. ### Stopping a session ```elixir theme={null} Firecrawl.stop_interactive_scrape_browser_session(job_id, api_key: "fc-YOUR_API_KEY") ``` ## Notes * **Naming style**: All parameters use snake\_case atoms in keyword lists. The SDK serializes to camelCase for the API. * **OpenAPI-generated**: The Elixir SDK is generated from the OpenAPI spec. Function names reflect the API operation IDs rather than shortened aliases. * **Function naming**: * Search: `search_and_scrape` (not `search`) * Scrape: `scrape_and_extract_from_url` (not `scrape`) * Interact: `interact_with_scrape_browser_session` (not `interact`) * Stop interaction: `stop_interactive_scrape_browser_session` * **Bang variants**: Every function has a `!` variant that raises `Firecrawl.Error` on non-2xx responses instead of returning `{:error, ...}`. * **Req-based**: The SDK uses the `Req` HTTP library. Runtime options (second or third argument) accept `:api_key`, `:base_url`, and any `Req` option. * **No deprecated aliases**: The Elixir SDK has no deprecated function names. ## Source Of Truth * `firecrawl/apps/elixir-sdk/lib/firecrawl.ex` * `firecrawl/apps/elixir-sdk/mix.exs` * `firecrawl-docs/api-reference/v2-openapi.json`