> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-rvebnp.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 via the Elixir SDK. It is generated from SDK source and the OpenAPI spec. ## Install Add to your `mix.exs`: ```elixir theme={null} defp deps do [ {:firecrawl, "~> 1.9"} ] end ``` ## Authenticate The Elixir SDK is a flat module of stateless functions — there is no client struct to construct. Configure the API key globally or pass it per request. **Global config** (in `config.exs`): ```elixir theme={null} config :firecrawl, api_key: "fc-YOUR_API_KEY" ``` **Per-request override:** ```elixir theme={null} Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR_API_KEY") ``` All functions accept trailing `opts` for `:api_key` and `:base_url` (defaults to `https://api.firecrawl.dev/v2`). ## When To Use What * **`search_and_scrape`** — Use when you start with a query and need to discover relevant pages. Returns structured results grouped by source type. Optionally scrapes each result. * **`scrape_and_extract_from_url`** — Use when you already have a URL and want page content in one or more formats (markdown, HTML, JSON extraction, etc.). * **`interact_with_scrape_browser_session`** — Use when the page needs post-scrape browser actions: running code in a live browser session tied to a previous scrape job. ## Search ### Why use it Search the web for a query and optionally scrape each result. Returns results grouped by source type. Use this as the starting point when you do not yet have a specific URL. ### Preferred SDK method ``` Firecrawl.search_and_scrape(params \\ [], opts \\ []) ``` Bang variant: `Firecrawl.search_and_scrape!(params, opts)` raises on error. ### Example ```elixir theme={null} {:ok, response} = Firecrawl.search_and_scrape( query: "firecrawl web scraping API", limit: 5 ) IO.inspect(response.body) ``` ### Parameters Parameters are passed as a keyword list. All are optional except `query`. | Parameter | Type | Description | | --------------------- | ------------------ | ------------------------------------------------------- | | `query` | `:string` | **Required.** The search query. | | `limit` | `:integer` | Max number of results. | | `sources` | `{:list, :any}` | Sources to search. Default: `["web"]`. | | `categories` | `{:list, :any}` | Categories to filter results. Default: `[]`. | | `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 for search results. | | `country` | `:string` | ISO country code for geo-targeting (e.g. `"US"`). | | `timeout` | `:integer` | Timeout in milliseconds. | | `highlights` | `:boolean` | Generate query-relevant highlights. Default: `true`. | | `ignore_invalid_urls` | `:boolean` | Exclude URLs invalid for other Firecrawl endpoints. | | `scrape_options` | `:keyword_list` | Options for scraping search results. | | `enterprise` | `{:list, :string}` | Enterprise ZDR options: `["zdr"]` or `["anon"]`. | ### Return shape `{:ok, %Req.Response{}}` — the response body contains results grouped by source type. ## Scrape ### Why use it Scrape a single URL and get its content in one or more formats. Use this when you have the exact URL you want content from. ### Preferred SDK method ``` Firecrawl.scrape_and_extract_from_url(params \\ [], opts \\ []) ``` Bang variant: `Firecrawl.scrape_and_extract_from_url!(params, opts)` raises on error. ### Example ```elixir theme={null} {:ok, response} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com", formats: ["markdown", "html"], only_main_content: true ) IO.inspect(response.body) ``` ### Parameters 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 (e.g. `"markdown"`, `"html"`, `"json"`, `"screenshot"`). Default: `["markdown"]`. | | `only_main_content` | `:boolean` | Only return main content. Default: `true`. | | `include_tags` | `{:list, :string}` | HTML tags to include. | | `exclude_tags` | `{:list, :string}` | HTML tags to exclude. | | `headers` | `:any` | Custom HTTP headers. | | `timeout` | `:integer` | Timeout in ms. Default: `60000`. Min 1000, max 300000. | | `wait_for` | `:integer` | Delay in ms before fetching content. | | `mobile` | `:boolean` | Emulate a mobile device. | | `parsers` | `{:list, :any}` | File parser config. Default: `["pdf"]`. | | `actions` | `{:list, :any}` | Browser actions to perform before grabbing content. | | `location` | `:keyword_list` | Location settings (proxy, language, timezone). | | `skip_tls_verification` | `:boolean` | Skip TLS certificate verification. | | `remove_base64_images` | `:boolean` | Remove base64 images from markdown. Default: `true`. | | `block_ads` | `:boolean` | Block ads and cookie popups. Default: `true`. | | `proxy` | `{:in, [:basic, :enhanced, :auto]}` | Proxy type. Default: `"auto"`. | | `max_age` | `:integer` | Max cache age in ms. Default: `172800000` (2 days). | | `min_age` | `:integer` | Cache-only mode. Min age in ms. Set to `1` for any cache. | | `store_in_cache` | `:boolean` | Store result in cache. Default: `true`. | | `lockdown` | `:boolean` | Only serve cached results. | | `redact_pii` | `:boolean` | Redact PII from content. | | `zero_data_retention` | `:boolean` | Enable zero data retention. | | `profile` | `:keyword_list` | Persistent browser profile. | | `audit_metadata` | `:keyword_list` | SIEM logging attribution (`username` required). | ## Interact ### Why use it Execute code in a live browser session tied to a previous scrape job. Use this for post-scrape interactions like clicking buttons, filling forms, or running scripts. ### Preferred SDK method ``` Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ []) ``` Bang variant: `Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts)` raises on error. ### Example ```elixir theme={null} {:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(url: "https://example.com") job_id = scrape_response.body["data"]["metadata"]["jobId"] {:ok, response} = Firecrawl.interact_with_scrape_browser_session(job_id, code: "document.querySelector('button#submit').click();", language: :node, timeout: 30 ) IO.inspect(response.body) ``` ### Parameters The first argument is the `job_id` (path parameter). Remaining parameters are passed as a keyword list. | Parameter | Type | Description | | ---------- | -------------------------------- | ----------------------------------------------------------------------------------------- | | `job_id` | `String.t()` | **Required** (first argument). The scrape job ID. | | `code` | `:string` | **Required.** Code to execute in the browser session. | | `language` | `{:in, [:python, :node, :bash]}` | Execution language. Use `:node` for JavaScript or `:bash` for agent-browser CLI commands. | | `timeout` | `:integer` | Execution timeout in seconds. | | `origin` | `:string` | Origin label for telemetry. | ### Related methods * `Firecrawl.stop_interactive_scrape_browser_session(job_id, opts)` — Stop the browser session (`DELETE /scrape/{jobId}/interact`). ## Notes * The SDK is **auto-generated from the OpenAPI spec**. Function names map 1:1 to OpenAPI operations. * Parameter names use **snake\_case** in Elixir. They are converted to camelCase for the JSON wire format automatically. * All functions return `{:ok, %Req.Response{}} | {:error, Exception.t() | Firecrawl.Error.t()}`. * Bang variants (e.g. `search_and_scrape!`) raise on error instead of returning an error tuple. * There is no client struct — the module is a flat namespace of stateless functions. * HTTP errors (4xx/5xx) are wrapped in `Firecrawl.Error` with `:status` and `:body` fields. * Batch scraping is available via `Firecrawl.scrape_and_extract_from_urls/2` (`POST /batch/scrape`). ## Source Of Truth * SDK: `firecrawl/apps/elixir-sdk/lib/firecrawl.ex` * OpenAPI: `firecrawl-docs/api-reference/v2-openapi.json`