> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-ismzye.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 external agents. Generated from SDK source (`firecrawl` Hex package) and the v2 OpenAPI spec. Function names match the auto-generated client from the OpenAPI spec. ## 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 webhook retries"], api_key: "fc-your-api-key" ) ``` Self-hosted: ```elixir theme={null} {:ok, res} = Firecrawl.scrape_and_extract_from_url( [url: "https://example.com"], base_url: "http://localhost:3002/v2", api_key: "fc-your-api-key" ) ``` ## When To Use What * `search`: use when you start with a query and need discovery. * `scrape`: use when you already have a URL and want page content. * `interact`: use when the page needs clicks, forms, or post-scrape browser actions. ## Search ### Why use it Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with `site:`, for example `site:docs.firecrawl.dev crawl webhooks`. ### Preferred SDK method `Firecrawl.search_and_scrape(params \\ [], opts \\ [])` ### 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 | Search query. Use `site:example.com` to limit to a domain. Required. | | `sources` | list | Sources: `:web`, `:news`, `:images`. Default: `[:web]`. | | `categories` | list | Filter by category. | | `limit` | integer | Cap the number of results. | | `tbs` | string | Time-based filter (e.g. `"qdr:d"`, `"qdr:w"`). | | `location` | string | Localized results. | | `country` | string | ISO country code for geo-targeting (e.g. `"US"`). | | `ignore_invalid_urls` | boolean | Drop URLs that cannot be scraped. | | `timeout` | integer | Request timeout in milliseconds. | | `scrape_options` | keyword list | Scrape each search result. See Scrape parameters. | | `include_domains` | list of strings | Only include results from these domains. | | `exclude_domains` | list of strings | Exclude results from these domains. | | `highlights` | boolean | Return highlights (defaults to true). | ## Scrape ### Why use it Use scrape when you already have a URL and want structured content in one or more formats. ### Preferred SDK method `Firecrawl.scrape_and_extract_from_url(params \\ [], opts \\ [])` ### Example ```elixir theme={null} {:ok, res} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com/pricing", formats: ["markdown", "links", %{"type" => "json", "prompt" => "Extract plan names and prices."}], only_main_content: true, wait_for: 1000 ) ``` ### Parameters | Parameter | Type | Description | | ----------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | string | The page URL to scrape. Required. | | `formats` | list | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"audio"`, `"video"`. Use maps for object forms. | | `headers` | any | Custom request headers. | | `include_tags` | list of strings | Include only specific HTML tags. | | `exclude_tags` | list of strings | Exclude specific HTML tags. | | `only_main_content` | boolean | Strip nav, footer, and boilerplate. | | `timeout` | integer | Timeout in milliseconds. Default: 60000, min: 1000, max: 300000. | | `wait_for` | integer | Wait for page render (milliseconds). | | `mobile` | boolean | Use a mobile viewport. | | `parsers` | list | Parser configs (e.g. PDF parsing). | | `actions` | list | Pre-scrape browser actions. | | `location` | keyword list | `[country: "US", languages: ["en-US"]]` for geo-aware scraping. | | `skip_tls_verification` | boolean | Skip TLS verification. | | `remove_base64_images` | boolean | Drop base64 images from markdown. | | `block_ads` | boolean | Block ads and cookie popups. | | `proxy` | atom | Proxy: `:basic`, `:enhanced`, `:auto`. | | `max_age` | integer | Use cached data up to this age (milliseconds). Default: 2 days. | | `min_age` | integer | Use cached data only if at least this old (milliseconds). | | `store_in_cache` | boolean | Cache the result. | | `lockdown` | boolean | Only serve cached results. | | `profile` | keyword list | `[name: "my-profile", save_changes: true]` for persistent browser profiles. | ## Interact ### Why use it Use interact for code-based control of the browser session tied to a scrape job. The Elixir SDK requires `code` (no `prompt` parameter). ### Preferred SDK method `Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ [])` ### Example ```elixir theme={null} {:ok, scrape_res} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com", formats: ["markdown"] ) job_id = get_in(scrape_res.body, ["data", "metadata", "scrapeId"]) {:ok, result} = Firecrawl.interact_with_scrape_browser_session( job_id, code: "console.log(await page.title());", language: :node, timeout: 60 ) # Stop the session when done {:ok, _} = Firecrawl.stop_interactive_scrape_browser_session(job_id) ``` ### Parameters | Parameter | Type | Description | | ---------- | ------- | ------------------------------------------------------- | | `job_id` | string | Scrape job ID from scrape response metadata `scrapeId`. | | `code` | string | Code to run in the browser session. Required. | | `language` | atom | Runtime: `:python`, `:node`, `:bash`. | | `timeout` | integer | Execution timeout in seconds. | ### Stop session `Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])` ## Notes * The Elixir client is **auto-generated from the OpenAPI spec** — function names are derived from operation IDs and may look verbose (e.g. `scrape_and_extract_from_url` instead of `scrape`). * All functions return `{:ok, %Req.Response{}}` or `{:error, exception}`. Bang variants (e.g. `scrape_and_extract_from_url!`) raise on error. * Parameters use `snake_case` keyword lists, but are converted to `camelCase` JSON for the API. * Atoms in parameter values (e.g. `:node`, `:web`) are converted to strings in the request body. * Per-call options (`api_key:`, `base_url:`) are passed in the second argument (opts). ## Source Of Truth * `firecrawl/apps/elixir-sdk/lib/firecrawl.ex` * `firecrawl/apps/elixir-sdk/mix.exs` * `firecrawl-docs/api-reference/v2-openapi.json`