> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-4ti4xi.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 Firecrawl via the Elixir SDK. It is generated from SDK source and OpenAPI spec. ## Install Add to `mix.exs`: ```elixir theme={null} defp deps do [ {:firecrawl, "~> 1.9"} ] end ``` Then run: ```bash theme={null} mix deps.get ``` ## Authenticate Set the API key globally in your config: ```elixir theme={null} # config/config.exs config :firecrawl, api_key: "fc-YOUR_API_KEY" ``` Or pass it per-request: ```elixir theme={null} Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR_API_KEY") ``` All functions accept an optional trailing keyword list (`opts`) that supports `:api_key` and `:base_url` (for self-hosted instances, default `"https://api.firecrawl.dev/v2"`). ## When To Use What * **`search_and_scrape`**: Use when you start with a query and need to discover relevant URLs and their content. * **`scrape_and_extract_from_url`**: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats. * **`interact_with_scrape_browser_session`**: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session. ## Search ### Why use it Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction. ### Preferred SDK method ```elixir theme={null} 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, highlights: true ) IO.inspect(response.body) ``` ### Parameters All parameters are passed as a keyword list. Only `query` is required. | Parameter | Elixir Key | JSON Key | Type | Description | | --------------------- | ---------------------- | --------------------- | ------------------ | --------------------------------------------------------------------- | | query | `:query` | `"query"` | `:string` | The search query (required). | | limit | `:limit` | `"limit"` | `:integer` | Maximum number of results. Server default: `10`. | | sources | `:sources` | `"sources"` | `{:list, :any}` | Sources to search: `"web"`, `"news"`, `"images"`. | | categories | `:categories` | `"categories"` | `{:list, :any}` | Filter by category: `"github"`, `"research"`, `"pdf"`, `"developer"`. | | include\_domains | `:include_domains` | `"includeDomains"` | `{:list, :string}` | Restrict results to these domains. | | exclude\_domains | `:exclude_domains` | `"excludeDomains"` | `{:list, :string}` | Exclude results from these domains. | | tbs | `:tbs` | `"tbs"` | `:string` | Time-based filter (e.g. `"qdr:d"` for past day). | | location | `:location` | `"location"` | `:string` | Location for geo-targeted search. | | country | `:country` | `"country"` | `:string` | ISO country code (e.g. `"US"`). | | ignore\_invalid\_urls | `:ignore_invalid_urls` | `"ignoreInvalidURLs"` | `:boolean` | Ignore invalid URLs in results. | | timeout | `:timeout` | `"timeout"` | `:integer` | Timeout in milliseconds. Server default: `60000`. | | highlights | `:highlights` | `"highlights"` | `:boolean` | Generate query-relevant highlights. Server default: `true`. | | scrape\_options | `:scrape_options` | `"scrapeOptions"` | `:keyword_list` | Nested scrape configuration. | | enterprise | `:enterprise` | `"enterprise"` | `{:list, :string}` | Enterprise ZDR options: `["zdr"]` or `["anon"]`. | ## Scrape ### Why use it Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more. ### Preferred SDK method ```elixir theme={null} 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["data"]["markdown"]) ``` ### Parameters All parameters are passed as a keyword list. Only `url` is required. | Parameter | Elixir Key | JSON Key | Type | Description | | ----------------------- | ------------------------ | ----------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | url | `:url` | `"url"` | `:string` | The URL to scrape (required). | | formats | `:formats` | `"formats"` | `{:list, :any}` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, etc. Server default: `["markdown"]`. | | only\_main\_content | `:only_main_content` | `"onlyMainContent"` | `:boolean` | Strip boilerplate. Server default: `true`. | | headers | `:headers` | `"headers"` | `:any` | Custom HTTP headers. | | include\_tags | `:include_tags` | `"includeTags"` | `{:list, :string}` | HTML tags to include. | | exclude\_tags | `:exclude_tags` | `"excludeTags"` | `{:list, :string}` | HTML tags to exclude. | | timeout | `:timeout` | `"timeout"` | `:integer` | Timeout in ms. Min: `1000`, max: `300000`. Server default: `60000`. | | wait\_for | `:wait_for` | `"waitFor"` | `:integer` | Delay in ms before fetching content. | | mobile | `:mobile` | `"mobile"` | `:boolean` | Emulate mobile device. | | parsers | `:parsers` | `"parsers"` | `{:list, :any}` | Parser configurations. Server default: `["pdf"]`. | | actions | `:actions` | `"actions"` | `{:list, :any}` | Browser automation actions. | | location | `:location` | `"location"` | `:keyword_list` | Location settings. | | skip\_tls\_verification | `:skip_tls_verification` | `"skipTlsVerification"` | `:boolean` | Skip TLS verification. | | remove\_base64\_images | `:remove_base64_images` | `"removeBase64Images"` | `:boolean` | Remove base64 images. Server default: `true`. | | block\_ads | `:block_ads` | `"blockAds"` | `:boolean` | Block advertisements. Server default: `true`. | | proxy | `:proxy` | `"proxy"` | `:basic \| :enhanced \| :auto` | Proxy type. Server default: `:auto`. | | max\_age | `:max_age` | `"maxAge"` | `:integer` | Use cached result if younger than this (ms). | | min\_age | `:min_age` | `"minAge"` | `:integer` | Cache-only mode. Set to `1` for any cached data. | | store\_in\_cache | `:store_in_cache` | `"storeInCache"` | `:boolean` | Cache the result. Server default: `true`. | | lockdown | `:lockdown` | `"lockdown"` | `:boolean` | Only serve cached results. | | redact\_pii | `:redact_pii` | `"redactPII"` | `:boolean` | Redact PII from content. | | profile | `:profile` | `"profile"` | `:keyword_list` | Browser profile for session continuity. | | audit\_metadata | `:audit_metadata` | `"auditMetadata"` | `:keyword_list` | User attribution: `[username: "..."]`. | | zero\_data\_retention | `:zero_data_retention` | `"zeroDataRetention"` | `:boolean` | Enable zero data retention. | ## Interact ### Why use it Execute code in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts. ### Preferred SDK method ```elixir theme={null} 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, result} = Firecrawl.interact_with_scrape_browser_session(job_id, code: "document.title", language: :node ) IO.inspect(result.body) Firecrawl.stop_interactive_scrape_browser_session(job_id) ``` ### Parameters The first argument is the `job_id` (string). Remaining parameters are passed as a keyword list. | Parameter | Elixir Key | JSON Key | Type | Description | | --------- | -------------- | ------------ | --------------------------- | ----------------------------------------------------------------- | | job\_id | first argument | URL path | `String.t()` | The scrape job ID (required). | | code | `:code` | `"code"` | `:string` | Code to execute in the browser sandbox (required). | | language | `:language` | `"language"` | `:python \| :node \| :bash` | Execution language. Server default: `:node`. | | timeout | `:timeout` | `"timeout"` | `:integer` | Execution timeout in seconds. Range: 1-300. Server default: `30`. | | origin | `:origin` | `"origin"` | `:string` | Origin label for telemetry. | Use `Firecrawl.stop_interactive_scrape_browser_session(job_id)` to end the browser session. ## Notes * **Naming style**: Parameters use snake\_case atom keys. The SDK converts them to camelCase JSON keys 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`, not `scrape`). * **Return type**: All functions return `{:ok, %Req.Response{}}` or `{:error, exception}`. The bang variants (`!`) raise on error and return `Req.Response.t()` directly. HTTP 4xx/5xx responses raise `Firecrawl.Error` with `:status` and `:body` fields. * **No `prompt` support**: Unlike JS/Python/Rust, the Elixir SDK `interact_with_scrape_browser_session` only accepts `code`, not a natural-language `prompt`. * **Origin auto-injection**: The SDK automatically injects `"origin": "elixir-sdk@{version}"` into 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`