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 (apps/elixir-sdk) plus the OpenAPI spec (api-reference/v2-openapi.json).

The Elixir SDK is auto-generated from the OpenAPI spec. Function names are verbose and OpenAPI-shaped — use them exactly as shown.

Install

Add firecrawl to your mix.exs:

defp deps do
  [
    {:firecrawl, "~> 1.0"}
  ]
end

Then run:

mix deps.get

Authenticate

Configure your API key in config/config.exs:

config :firecrawl, api_key: System.get_env("FIRECRAWL_API_KEY")

Or pass it per-request:

Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR-API-KEY")

All functions accept a trailing opts keyword list supporting:

Option	Type	Default	Description
:api_key	string	Application config :firecrawl, :api_key	Override the API key. Omit for keyless free tier.
:base_url	string	"https://api.firecrawl.dev/v2"	Override for self-hosted instances.

When To Use What

• search_and_scrape — Use when you start with a query and need to discover relevant pages.
• scrape_and_extract_from_url — Use when you already have a URL and want page content.
• interact_with_scrape_browser_session — Use when the page needs code execution in a post-scrape browser session.

Search

Why use it

Search the web with a query and get structured results. Each result can optionally include full scraped page content.

Preferred SDK function

Firecrawl.search_and_scrape(params, opts \\ [])
Firecrawl.search_and_scrape!(params, opts \\ [])  # bang variant, raises on error

Example

{:ok, result} = Firecrawl.search_and_scrape(query: "firecrawl web scraping", limit: 5)

for entry <- result.body["data"]["web"] do
  IO.puts("#{entry["title"]} - #{entry["url"]}")
end

Parameters

Pass as a keyword list. All parameters use snake_case keys; the SDK converts to camelCase for the API.

Parameter	Type	Required	Description
:query	string	yes	The search query.
:sources	list(any)	no	Sources to search. Server default: ["web"].
:categories	list(any)	no	Category filters for results.
:include_domains	list(string)	no	Only include results from these domains.
:exclude_domains	list(string)	no	Exclude results from these domains.
:limit	integer	no	Max number of results.
:tbs	string	no	Time-based search filter (e.g. "qdr:d" for past day).
:location	string	no	Geographic location for results.
:country	string	no	ISO country code for geo-targeting.
:ignore_invalid_urls	boolean	no	Exclude invalid URLs from results.
:timeout	integer	no	Timeout in milliseconds.
:highlights	boolean	no	Generate query-relevant highlights. Server default: true.
:scrape_options	keyword	no	Options applied when scraping each result.
:enterprise	list(string)	no	Enterprise options: ["zdr"] for Zero Data Retention, ["anon"] for anonymized.

Response

Returns {:ok, %Req.Response{}} or {:error, exception}. Access data via result.body["data"].

Scrape

Why use it

Fetch a single URL and get back clean content in your chosen formats: markdown, HTML, screenshots, structured JSON extraction, and more.

Preferred SDK function

Firecrawl.scrape_and_extract_from_url(params, opts \\ [])
Firecrawl.scrape_and_extract_from_url!(params, opts \\ [])  # bang variant

Example

{:ok, result} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com",
  formats: ["markdown", "links"]
)

IO.puts(result.body["data"]["markdown"])

Parameters

Parameter	Type	Required	Description
:url	string	yes	The URL to scrape.
:formats	list(any)	no	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "json", "audio", "video", etc.
:headers	any	no	Custom HTTP headers (cookies, user-agent).
:include_tags	list(string)	no	HTML tags to include.
:exclude_tags	list(string)	no	HTML tags to exclude.
:only_main_content	boolean	no	Strip navbars, footers, sidebars.
:timeout	integer	no	Timeout in ms. Default: 60000, max: 300000.
:wait_for	integer	no	Delay in ms before fetching content.
:mobile	boolean	no	Emulate a mobile device.
:parsers	list(any)	no	File parser config (e.g. PDF).
:actions	list(any)	no	Browser actions before extraction.
:location	keyword	no	Location settings for proxy/language.
:skip_tls_verification	boolean	no	Skip TLS certificate verification.
:remove_base64_images	boolean	no	Remove base64 images from markdown.
:block_ads	boolean	no	Block ads and cookie popups.
:proxy	:basic | :enhanced | :auto	no	Proxy routing mode.
:max_age	integer	no	Max cache age in ms.
:min_age	integer	no	Min cache age in ms for cache-only mode.
:store_in_cache	boolean	no	Store result in cache.
:lockdown	boolean	no	Only serve cached results.
:redact_pii	boolean	no	Redact PII.
:profile	keyword	no	Persistent browser profile (:name, :save_changes).
:audit_metadata	keyword	no	SIEM audit attribution (:username).

Interact

Why use it

After scraping a page, use interact_with_scrape_browser_session to execute code in the live browser session: run Playwright scripts in Node.js, Python, or Bash.

Preferred SDK function

Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ [])
Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts \\ [])  # bang variant

Stop the session when done:

Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])
Firecrawl.stop_interactive_scrape_browser_session!(job_id, opts \\ [])

Example

{:ok, scrape} = Firecrawl.scrape_and_extract_from_url(
  url: "https://www.amazon.com",
  formats: ["markdown"]
)

scrape_id = get_in(scrape.body, ["data", "metadata", "scrapeId"])

{:ok, run} = Firecrawl.interact_with_scrape_browser_session(
  scrape_id,
  code: ~s|const title = await page.title(); console.log(title);|,
  language: :node
)

IO.inspect(run.body)

Firecrawl.stop_interactive_scrape_browser_session(scrape_id)

Parameters

Parameter	Type	Required	Description
job_id	String.t()	yes	(first arg) The scrapeId from a prior scrape’s metadata.
:code	string	yes	Code to execute in the browser sandbox.
:language	:python | :node | :bash	no	Language of the code. Use :node for JavaScript.
:timeout	integer	no	Execution timeout in seconds.
:origin	string	no	Request attribution label.

Interact limitation: no prompt support

The Elixir SDK’s interact_with_scrape_browser_session requires code — it does not currently support the prompt parameter for natural-language browser interaction. For prompt-based interaction, use the REST API directly:

headers = [
  {"Authorization", "Bearer #{Application.get_env(:firecrawl, :api_key)}"},
  {"Content-Type", "application/json"}
]

{:ok, response} = Req.post(
  "https://api.firecrawl.dev/v2/scrape/#{scrape_id}/interact",
  json: %{prompt: "Search for iPhone 16 Pro Max"},
  headers: headers
)

IO.inspect(response.body)

Notes

• Function names: The Elixir SDK is auto-generated from the OpenAPI spec. Function names are verbose (e.g. scrape_and_extract_from_url, search_and_scrape, interact_with_scrape_browser_session). Use them exactly as documented.
• Naming: Parameters use snake_case keys in keyword lists. The SDK converts to camelCase for the API.
• Bang variants: Every function has a ! bang variant that raises on error instead of returning {:error, ...}.
• Return type: Non-bang functions return {:ok, %Req.Response{}} or {:error, exception}. Access response data via result.body["data"].
• Interact prompt: Not supported in the SDK. Use raw Req.post to the REST API for prompt-based interaction.

Source Of Truth

• firecrawl/apps/elixir-sdk/mix.exs
• firecrawl/apps/elixir-sdk/lib/firecrawl.ex
• firecrawl-docs/api-reference/v2-openapi.json