> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-21lyl6.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 Canonical quickstart for agents integrating Firecrawl via the Elixir SDK. Generated from SDK source (`firecrawl` hex package) and the v2 OpenAPI spec. Function names and parameters match the auto-generated OpenAPI client. ## Install Add to `mix.exs`: ```elixir theme={null} {:firecrawl, "~> 1.9"} ``` ## Authenticate ```elixir theme={null} # config/runtime.exs or config.exs config :firecrawl, api_key: System.get_env("FIRECRAWL_API_KEY") # or pass api_key per call {:ok, res} = Firecrawl.search_and_scrape( [query: "site:docs.firecrawl.dev webhooks"], api_key: "fc-your-api-key" ) ``` ## When To Use What * **`search`**: use when you start with a query and need discovery. Returns categorized results from web, news, and image sources. * **`scrape`**: use when you already have a URL and want page content in one or more formats (markdown, HTML, JSON extraction, screenshots, etc.). * **`interact`**: use when the page needs clicks, forms, or post-scrape browser actions. Operates on a browser session created by a prior scrape. ## Search ### Why use it Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with `site:` in the query (e.g. `site:docs.firecrawl.dev webhooks`). ### Preferred SDK method `Firecrawl.search_and_scrape(params \\ [], opts \\ [])` → `{:ok, %Req.Response{}}` or `{:error, exception}` Bang variant: `Firecrawl.search_and_scrape!(params, opts)` raises on error. ### Example ```elixir theme={null} {:ok, res} = Firecrawl.search_and_scrape( query: "site:docs.firecrawl.dev webhook retries", sources: [:web], limit: 5, scrape_options: [ formats: ["markdown"], only_main_content: true ] ) ``` ### Parameters | Parameter | Type | Description | | --------------------- | ------------------------------- | ------------------------------------------------------------------------- | | `query` | string (required) | Search query. Use `site:example.com` to scope to a domain. | | `sources` | list of atoms, strings, or maps | Which source types: `:web`, `:news`, `:images`, or `%{type: "web"}`. | | `categories` | list of atoms, strings, or maps | Category filters: `:github`, `:research`, `:pdf`, or `%{type: "github"}`. | | `include_domains` | list of strings | Restrict results to these domains. | | `exclude_domains` | list of strings | Exclude results from these domains. | | `limit` | integer | Max number of results. | | `tbs` | string | Time-based filter (e.g. `qdr:d`, `qdr:w`). | | `location` | string | Location string for geo-targeted results. | | `country` | string | ISO 3166-1 alpha-2 country code (e.g. `"US"`). | | `ignore_invalid_urls` | boolean | Drop URLs that cannot be scraped. | | `timeout` | integer | Request timeout in milliseconds. | | `highlights` | boolean | Generate query-relevant highlights. Defaults to `true`. | | `enterprise` | list of strings | Enterprise options: `"zdr"`, `"anon"`. | | `scrape_options` | keyword list | Scrape each search result (see Scrape parameters). | ## Scrape ### Why use it Get structured content from a URL in one or more formats: markdown, HTML, JSON extraction, screenshots, and more. ### Preferred SDK method `Firecrawl.scrape_and_extract_from_url(params \\ [], opts \\ [])` → `{:ok, %Req.Response{}}` or `{:error, exception}` Bang variant: `Firecrawl.scrape_and_extract_from_url!(params, opts)` raises on error. ### Example ```elixir theme={null} {:ok, res} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com/pricing", formats: [ "markdown", %{type: "json", prompt: "Extract plan names and prices."} ], only_main_content: true ) ``` ### Parameters | Parameter | Type | Description | | ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | string (required) | URL to scrape. | | `formats` | list of strings or maps | Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`. Maps: `%{type: "json", prompt: ...}`, `%{type: "screenshot", fullPage: true}`, `%{type: "changeTracking", modes: ["git-diff"]}`. | | `headers` | map | Custom HTTP headers. | | `include_tags` | list of strings | Only include these HTML tags. | | `exclude_tags` | list of strings | Exclude these HTML tags. | | `only_main_content` | boolean | Strip nav, footer, and boilerplate. | | `timeout` | integer | Timeout in milliseconds. Default 60000, range 1000–300000. | | `wait_for` | integer | Wait for the page to render (milliseconds). | | `mobile` | boolean | Use mobile viewport. | | `parsers` | list of strings or maps | File parsing. E.g. `"pdf"` or `%{type: "pdf", mode: "auto", maxPages: 5}`. | | `actions` | list of maps | Pre-scrape browser actions. Types: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`. | | `location` | keyword list | Geo/language-aware scraping. Keys: `country:`, `languages:`. | | `skip_tls_verification` | boolean | Skip TLS verification. | | `remove_base64_images` | boolean | Drop base64 images from markdown output. | | `block_ads` | boolean | Block ads and cookie popups. | | `proxy` | atom | Proxy mode: `:basic`, `:enhanced`, `:auto`. | | `max_age` | integer | Max age (ms) of cached content to reuse. | | `min_age` | integer | Min age (ms) of cached content. | | `store_in_cache` | boolean | Store result in Firecrawl cache. | | `profile` | keyword list | Persistent browser profile. Keys: `name:`, `save_changes:`. | | `zero_data_retention` | boolean | Enable zero data retention. | | `lockdown` | boolean | Only serve cached results, no outbound request. | | `redact_pii` | boolean | Redact personally identifiable information. | ## Interact ### Why use it Control the browser session tied to a prior scrape job. Use for code execution in the browser runtime. ### Preferred SDK method `Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ [])` → `{:ok, %Req.Response{}}` or `{:error, exception}` Bang variant: `Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts)` raises on error. ### Example ```elixir theme={null} {:ok, res} = Firecrawl.interact_with_scrape_browser_session( "", code: "console.log(await page.title());", language: :node, timeout: 60 ) # When done, stop the session: {:ok, _} = Firecrawl.stop_interactive_scrape_browser_session("") ``` ### Parameters | Parameter | Type | Description | | ---------- | -------------------------- | ------------------------------------------------ | | `job_id` | string (required, 1st arg) | Scrape job ID from the scrape response metadata. | | `code` | string (required) | Code to execute in the browser session. | | `language` | atom or string | Runtime: `:python`, `:node`, `:bash`. | | `timeout` | integer | Execution timeout in seconds. | ### Stop session `Firecrawl.stop_interactive_scrape_browser_session(job_id)` ends the browser session. ## Notes * The Elixir client is **auto-generated from the OpenAPI spec**; function names are derived from operation IDs, not hand-written aliases. * This SDK exposes **code-based interactions only**: there is no `prompt` parameter on `interact_with_scrape_browser_session`. * Each function has a bang (`!`) variant that raises on error instead of returning `{:error, _}`. * The SDK appends `"origin": "elixir-sdk@"` to every request body for telemetry. * Uses `snake_case` parameter keys in Elixir, converted to `camelCase` JSON keys on the wire. ## Source Of Truth * `firecrawl/apps/elixir-sdk/mix.exs` * `firecrawl/apps/elixir-sdk/lib/firecrawl.ex` * `firecrawl-docs/api-reference/v2-openapi.json`