> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-ofbvcu.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 official Elixir SDK. It is generated from SDK source and OpenAPI spec. ## Install Add to your `mix.exs`: ```elixir theme={null} defp deps do [ {:firecrawl, "~> 1.9"} ] end ``` Then run: ```bash theme={null} mix deps.get ``` ## Authenticate Configure via application config: ```elixir theme={null} # config/config.exs config :firecrawl, api_key: "fc-YOUR_API_KEY" ``` Or pass the API key per-request via the `opts` keyword: ```elixir theme={null} Firecrawl.search_and_scrape([query: "example"], api_key: "fc-YOUR_API_KEY") ``` For self-hosted instances, set the base URL: ```elixir theme={null} config :firecrawl, api_key: "fc-YOUR_API_KEY", base_url: "https://your-firecrawl-instance.com/v2" ``` The default base URL is `"https://api.firecrawl.dev/v2"`. Omitting the API key enables the keyless free tier (rate-limited per IP). ## When To Use What * **`search_and_scrape`** -- Use when you start with a query and need to discover relevant URLs and their content. Returns categorized results from web, news, and images. * **`scrape_and_extract_from_url`** -- Use when you already have a URL and want to extract page content in structured formats (markdown, HTML, JSON, screenshots, etc.). * **`interact_with_scrape_browser_session`** -- Use when the page needs post-scrape browser actions: running code in the live browser session. ## Search ### Why use it Search finds relevant pages across the web for a given query, optionally scraping the results. It returns results grouped by source type. ### Preferred SDK function ```elixir theme={null} Firecrawl.search_and_scrape(params, opts \\ []) Firecrawl.search_and_scrape!(params, opts \\ []) ``` ### Example ```elixir theme={null} {:ok, results} = Firecrawl.search_and_scrape( query: "firecrawl web scraping API", limit: 5, highlights: true ) IO.inspect(results) ``` The bang variant raises `Firecrawl.Error` on failure: ```elixir theme={null} results = Firecrawl.search_and_scrape!( query: "firecrawl web scraping API", limit: 5 ) ``` ### Parameters All parameters are passed as a keyword list. Only `query` is required. | Parameter | Type | Description | | --------------------- | ------------------ | ----------------------------------------------------------------------------------------- | | `query` | `:string` | The search query (required). | | `limit` | `:integer` | Maximum number of results to return. | | `sources` | `{:list, :any}` | Source types to search. Defaults to `["web"]`. | | `categories` | `{:list, :any}` | Filter results by category. | | `include_domains` | `{:list, :string}` | Only include results from 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` | Geographic location for search results (e.g. `"San Francisco,California,United States"`). | | `country` | `:string` | ISO country code for geo-targeting (e.g. `"US"`). | | `ignore_invalid_urls` | `:boolean` | Exclude invalid URLs from results. | | `timeout` | `:integer` | Timeout in milliseconds. | | `highlights` | `:boolean` | Generate query-relevant highlights. Defaults to `true`. | | `scrape_options` | `:keyword_list` | Options for scraping search results. Accepts the same parameters as scrape. | | `enterprise` | `{:list, :string}` | Enterprise ZDR options: `["zdr"]` or `["anon"]`. | ## Scrape ### Why use it Scrape extracts content from a single URL and returns it in one or more formats: markdown, HTML, raw HTML, JSON (via schema), screenshots, links, images, audio, video, and more. ### 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, doc} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com", formats: ["markdown", "links"] ) IO.puts(doc["data"]["markdown"]) ``` ### Parameters All parameters are passed as a keyword list. Only `url` is required. | Parameter | Type | Description | | ----------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `:string` | The URL to scrape (required). | | `formats` | `{:list, :any}` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"audio"`, `"video"`, etc. | | `headers` | `:any` | Custom HTTP headers (cookies, user-agent, etc.). | | `include_tags` | `{:list, :string}` | Only include content from these HTML tags. | | `exclude_tags` | `{:list, :string}` | Exclude content from these HTML tags. | | `only_main_content` | `:boolean` | Only return main content, excluding navbars, footers, etc. | | `timeout` | `:integer` | Timeout in milliseconds. Default: `60000`, Min: `1000`, Max: `300000`. | | `wait_for` | `:integer` | Wait time in milliseconds before scraping. | | `mobile` | `:boolean` | Scrape as a mobile device. | | `parsers` | `{:list, :any}` | File processing control (e.g. PDF settings). | | `actions` | `{:list, :any}` | Actions to execute before content extraction. | | `location` | `:keyword_list` | Geolocation settings. Defaults to US. | | `skip_tls_verification` | `:boolean` | Skip TLS certificate verification. | | `remove_base64_images` | `:boolean` | Remove base64-encoded images from markdown output. | | `block_ads` | `:boolean` | Block advertisements and cookie popups. | | `proxy` | `{:in, [:basic, :enhanced, :auto]}` | Proxy type. | | `max_age` | `:integer` | Use cached result if younger than this many milliseconds. Defaults to 2 days. | | `min_age` | `:integer` | Cache-only mode; minimum age in milliseconds. | | `store_in_cache` | `:boolean` | Whether to cache the result. | | `lockdown` | `:boolean` | Only serve previously cached results. | | `redact_pii` | `:boolean` | Redact personally identifiable information. | | `audit_metadata` | `:keyword_list` | User attribution for SIEM logging. Keys: `username` (required). | | `profile` | `:keyword_list` | Persistent browser storage across sessions. | | `zero_data_retention` | `:boolean` | Enable zero data retention. | ## Interact ### Why use it Interact lets you execute code in a live browser session that was opened by a prior scrape call. Use it for clicking buttons, filling forms, navigating multi-step flows, or extracting dynamic content. ### 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} {:ok, doc} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com", formats: ["markdown"] ) job_id = doc["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.inspect(result) ``` ### Parameters The `job_id` is passed as the first positional argument. Remaining parameters are a keyword list. | Parameter | Type | Description | | ---------- | -------------------------------- | ---------------------------------------------------------------------- | | `job_id` | `String.t()` | The scrape job ID from a prior scrape call (required, first argument). | | `code` | `:string` | Code to execute in the browser sandbox (required). | | `language` | `{:in, [:python, :node, :bash]}` | Language for code execution. | | `timeout` | `:integer` | Execution timeout in seconds. | | `origin` | `:string` | Origin label for telemetry. | ### Stopping a session ```elixir theme={null} {:ok, result} = Firecrawl.stop_interactive_scrape_browser_session(job_id) ``` ## Notes * **Naming style:** Function names and parameters use snake\_case, matching Elixir conventions. The SDK converts to camelCase for the API automatically. * **OpenAPI-generated:** The Elixir SDK is auto-generated from the OpenAPI spec. Function names match the OpenAPI operation IDs directly (e.g. `scrape_and_extract_from_url` rather than just `scrape`). * **Return values:** Regular functions return `{:ok, response}` or `{:error, %Firecrawl.Error{}}`. Bang variants (`!`) return the response directly or raise. * **No deprecated aliases:** The Elixir SDK does not have deprecated method aliases. * **Per-request options:** The trailing `opts` keyword list can include `api_key:` and `base_url:` to override the application config for a single request. * **Origin:** The SDK automatically injects `"elixir-sdk@{version}"` as the origin in every request body. ## Source Of Truth * `/firecrawl/apps/elixir-sdk/lib/firecrawl.ex` * `/firecrawl/apps/elixir-sdk/mix.exs` * `/firecrawl-docs/api-reference/v2-openapi.json`