> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-3bepuq.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 integrating with Firecrawl using the Elixir SDK. Generated from SDK source and OpenAPI spec. ## Install Add to your `mix.exs` dependencies: ```elixir theme={null} defp deps do [ {:firecrawl, "~> 1.9"} ] end ``` Then run: ```bash theme={null} mix deps.get ``` ## Authenticate Configure the API key in your application config: ```elixir theme={null} # config/config.exs config :firecrawl, api_key: "fc-YOUR_API_KEY" ``` Or pass the API key per-call via the `opts` keyword list: ```elixir theme={null} Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR_API_KEY" ) ``` The API key is sent as a Bearer token. A nil or empty key falls back to the keyless free tier (rate-limited per IP). You can also override the base URL per-call: ```elixir theme={null} Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], base_url: "https://your-instance.example.com/v2" ) ``` ## When To Use What * **`search_and_scrape`**: You start with a query and need to discover relevant URLs and their content. Use when you don't have a specific URL yet. * **`scrape_and_extract_from_url`**: You already have a URL and want its page content as markdown, HTML, or structured JSON. Use for targeted extraction. * **`interact_with_scrape_browser_session`**: The page needs clicks, form fills, or other browser actions after an initial scrape. Use for multi-step browser automation. ## Search ### Why use it Search the web for a query and optionally scrape the results. Returns structured results grouped by source type (web, news, images). Use this when you need to discover relevant pages before extracting content. ### Preferred SDK method ```elixir theme={null} Firecrawl.search_and_scrape(params, opts \\ []) ``` Bang variant `search_and_scrape!/2` 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"]] ) # response is a %Req.Response{} with JSON body for result <- response.body["data"]["web"] || [] do IO.puts("#{result["title"]} #{result["url"]}") IO.puts(result["markdown"]) end ``` ### Parameters All parameters are passed as a keyword list. Required parameters are marked. | Parameter | Type | Description | | --------------------- | --------------- | --------------------------------------------------------------------- | | `query` | `:string` | **Required.** The search query string. | | `sources` | `list(any)` | Sources to search: `"web"`, `"news"`, `"images"`. Default: `["web"]`. | | `categories` | `list(any)` | Narrow results by category. | | `include_domains` | `list(string)` | Restrict results to these domains. | | `exclude_domains` | `list(string)` | Exclude results from these domains. | | `limit` | `:integer` | Max results per source type. | | `tbs` | `:string` | Time-based filter. `"qdr:d"` (day), `"qdr:w"` (week), etc. | | `location` | `:string` | Geographic location for results. | | `country` | `:string` | ISO country code for geo-targeting. | | `timeout` | `:integer` | Timeout in milliseconds. | | `highlights` | `:boolean` | Generate query-relevant highlights. Default: `true`. | | `ignore_invalid_urls` | `:boolean` | Exclude invalid URLs. | | `scrape_options` | `:keyword_list` | Scrape options applied to each result. | | `enterprise` | `list(string)` | Enterprise options: `["zdr"]`, `["anon"]`. | ## Scrape ### Why use it Scrape a single URL and get its content as markdown, HTML, screenshots, structured JSON, or other formats. The primary tool for extracting page content when you already know the URL. ### Preferred SDK method ```elixir theme={null} Firecrawl.scrape_and_extract_from_url(params, opts \\ []) ``` Bang variant `scrape_and_extract_from_url!/2` raises on error. ### Example ```elixir theme={null} {:ok, response} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com", formats: ["markdown", "links"], only_main_content: true ) doc = response.body["data"] IO.puts(doc["markdown"]) IO.inspect(doc["links"]) ``` ### Parameters | Parameter | Type | Description | | ----------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `url` | `:string` | **Required.** The URL to scrape. | | `formats` | `list(any)` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. 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 milliseconds. Default: `60000`. Range: 1000-300000. | | `wait_for` | `:integer` | Delay in ms before fetching. | | `mobile` | `:boolean` | Emulate a mobile device. | | `parsers` | `list(any)` | Parser config (e.g. PDF). | | `actions` | `list(any)` | Browser actions before grabbing content. | | `location` | `:keyword_list` | Location settings. Default country: `"US"`. | | `skip_tls_verification` | `:boolean` | Skip TLS verification. | | `remove_base64_images` | `:boolean` | Remove base64 images from markdown. | | `block_ads` | `:boolean` | Block ads and cookie popups. | | `proxy` | `:basic \| :enhanced \| :auto` | Proxy type. Pass as atoms. | | `max_age` | `:integer` | Use cached result if younger (ms). Default: 2 days. | | `min_age` | `:integer` | Cache-only mode with minimum age (ms). | | `store_in_cache` | `:boolean` | Store result in cache. | | `lockdown` | `:boolean` | Serve only cached results. | | `redact_pii` | `:boolean` | Redact PII. | | `profile` | `:keyword_list` | Browser profile: `[name: "my-profile"]`. | | `audit_metadata` | `:keyword_list` | SIEM attribution: `[username: "user@example.com"]`. | | `zero_data_retention` | `:boolean` | Enable zero data retention. | ## Interact ### Why use it Execute code in the browser session created by a prior scrape. Use this for multi-step workflows: scrape a page first to get a job ID, then interact with the live browser to click buttons, fill forms, or run JavaScript. ### Preferred SDK method ```elixir theme={null} Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ []) ``` Bang variant `interact_with_scrape_browser_session!/3` raises on error. ### Example ```elixir theme={null} # First scrape to get a session {:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url( url: "https://example.com", formats: ["markdown"] ) job_id = scrape_response.body["data"]["metadata"]["jobId"] # Execute code in the browser {:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id, code: "document.querySelector('button.load-more').click();", language: :node, timeout: 30 ) IO.puts(result.body["stdout"]) # Stop the session when done Firecrawl.stop_interactive_scrape_browser_session(job_id) ``` ### Parameters | Parameter | Type | Description | | ---------- | --------------------------- | ------------------------------------------------------------------------------- | | `job_id` | `String.t()` | **Required.** First positional argument. The scrape job ID from a prior scrape. | | `code` | `:string` | **Required.** Code to execute in the browser sandbox. | | `language` | `:python \| :node \| :bash` | Language for code execution. Pass as atom. | | `timeout` | `:integer` | Execution timeout in seconds. | The response body includes: | Field | Type | Description | | -------------------------- | ----------------- | ------------------------------------------ | | `"success"` | `boolean` | Whether execution succeeded. | | `"stdout"` | `string \| null` | Standard output from code execution. | | `"result"` | `string \| null` | Alias for stdout. | | `"stderr"` | `string \| null` | Standard error output. | | `"exitCode"` | `integer \| null` | Exit code of executed process. | | `"killed"` | `boolean` | Whether process was killed due to timeout. | | `"liveViewUrl"` | `string \| null` | Read-only live view of the browser. | | `"interactiveLiveViewUrl"` | `string \| null` | Interactive live view. | Call `Firecrawl.stop_interactive_scrape_browser_session(job_id)` to end the session. ## Notes * The Elixir SDK is **auto-generated from the OpenAPI spec** via `mix run generate.exs`. Function names match the OpenAPI operation IDs converted to snake\_case. * Function names are longer than other SDKs because they follow the OpenAPI operation IDs: `scrape_and_extract_from_url` (not `scrape`), `search_and_scrape` (not `search`), `interact_with_scrape_browser_session` (not `interact`). * All parameters use **snake\_case** in Elixir. The SDK converts to camelCase for the API wire format. * Enum values are passed as **atoms**: `proxy: :auto`, `language: :node`. * All functions return `{:ok, %Req.Response{}}` or `{:error, exception}`. Use bang variants (`!`) to raise instead. * HTTP 4xx/5xx responses are wrapped in `Firecrawl.Error` with `status` and `body` fields. * Parameters are validated at runtime via NimbleOptions. Invalid params return `{:error, %NimbleOptions.ValidationError{}}`. * The Elixir SDK's `interact_with_scrape_browser_session` does not support a `prompt` parameter (unlike Node.js, Python, and Rust). Use `code` with the appropriate language. * There are **no deprecated aliases** in the Elixir SDK. ## Source Of Truth * SDK: `firecrawl/apps/elixir-sdk/lib/firecrawl.ex` * OpenAPI: `firecrawl-docs/api-reference/v2-openapi.json`