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 Firecrawl with Elixir. Generated from SDK source and OpenAPI spec. The Elixir SDK is auto-generated from the OpenAPI spec, so function names mirror the API operation names.

Install

Add to mix.exs:

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

Then run:

mix deps.get

Authenticate

Add to your config:

config :firecrawl, api_key: "fc-YOUR-API-KEY"

Or pass api_key per-request:

Firecrawl.search_and_scrape([query: "firecrawl"], api_key: "fc-YOUR-API-KEY")

All functions accept a trailing opts keyword list supporting:

Option	Type	Description
api_key	string	Override the configured API key.
base_url	string	Override the base URL. Default: "https://api.firecrawl.dev/v2".

Additional keys in opts are passed through to Req.

When To Use What

• search: Start with a query, discover relevant URLs, and get their content in one call.
• scrape: You already have a URL and want its page content as markdown, HTML, JSON, or other formats.
• interact: The page needs clicks, form fills, or post-scrape browser actions on a live session.

Search

Why use it

Search the web for a query and get scraped content from the top results. Combines discovery and content extraction in one call.

Preferred SDK method

Firecrawl.search_and_scrape(params, opts \\ [])

Example

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

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

Every function also has a bang variant (search_and_scrape!) that raises on error instead of returning {:error, ...}.

Parameters

All parameters are passed as a keyword list.

Parameter	Type	Description
query	string	Required. Search query.
limit	integer	Max results per source type.
sources	list	Sources to search. Default: ["web"].
categories	list	Category filters.
include_domains	list(string)	Restrict to these domains. Cannot combine with exclude_domains.
exclude_domains	list(string)	Exclude these domains. Cannot combine with include_domains.
tbs	string	Time-based filter (e.g. "qdr:d" past day).
location	string	Geo-targeting location string.
country	string	ISO country code (e.g. "US").
ignore_invalid_urls	boolean	Exclude invalid URLs.
timeout	integer	Timeout in ms.
highlights	boolean	Generate query-relevant highlights. Default: true.
scrape_options	keyword_list	Scrape options applied to each result page.
enterprise	list(string)	ZDR options: ["zdr"] or ["anon"].

Scrape

Why use it

Get the content of a single URL as markdown, HTML, JSON, screenshots, or other formats.

Preferred SDK method

Firecrawl.scrape_and_extract_from_url(params, opts \\ [])

Example

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

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

Parameters

All parameters are passed as a keyword list.

Parameter	Type	Description
url	string	Required. URL to scrape.
formats	list	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "changeTracking", "branding", "product", "menu", "audio", "video". Default: ["markdown"].
headers	any	Custom HTTP headers.
include_tags	list(string)	HTML tags to include.
exclude_tags	list(string)	HTML tags to exclude.
only_main_content	boolean	Strip navbars, footers, boilerplate. Default: true.
timeout	integer	Timeout in ms. Default: 60000. Min: 1000, Max: 300000.
wait_for	integer	Extra delay in ms before fetching content.
mobile	boolean	Emulate a mobile device.
parsers	list	File processing controls (e.g. PDF).
actions	list	Browser actions before content capture.
location	keyword_list	Geo settings. Country defaults to "US".
skip_tls_verification	boolean	Skip TLS certificate verification.
remove_base64_images	boolean	Remove base64 images from markdown.
block_ads	boolean	Block ads and cookie popups.
proxy	:basic | :enhanced | :auto	Proxy type. Default: "auto".
max_age	integer	Cache threshold in ms. Default: 2 days.
min_age	integer	Cache-only mode minimum age in ms.
store_in_cache	boolean	Store result in cache.
lockdown	boolean	Cache-only, no outbound requests.
redact_pii	boolean	Redact PII.
audit_metadata	keyword_list	SIEM logging. Required key: username (string).
profile	keyword_list	Persistent browser profile.
zero_data_retention	boolean	Enable zero data retention.

Interact

Why use it

Control a live browser session tied to a scrape job. Execute code in the browser sandbox to click buttons, fill forms, navigate, and extract dynamic content.

Preferred SDK method

Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ [])

Example

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

scrape_id = result["data"]["metadata"]["scrapeId"]

{:ok, response} = Firecrawl.interact_with_scrape_browser_session(scrape_id,
  code: "document.querySelector('input[name=field-keywords]').value = 'iPhone 16 Pro Max'"
)

Firecrawl.stop_interactive_scrape_browser_session(scrape_id)

Parameters

Parameter	Type	Description
job_id	String.t	Required. First positional argument. Scrape job ID from response metadata.
code	string	Required. Code to execute in the browser sandbox.
language	:python | :node | :bash	Runtime for code execution. Default: "node".
timeout	integer	Execution timeout in seconds. Min: 1, Max: 300.
origin	string	Origin label for telemetry.

Stop the session when done:

Firecrawl.stop_interactive_scrape_browser_session(scrape_id)

Notes

• Parameter names use snake_case and are passed as keyword lists.
• The Elixir SDK is auto-generated from the OpenAPI spec, so function names are verbose and mirror API operation names directly.
• The interact function requires code — it does not support a prompt parameter. Use the code parameter with JavaScript to control the browser.
• Every function has a bang variant (! suffix) that raises Firecrawl.Error instead of returning {:error, ...}.
• An origin field ("elixir-sdk@{version}") is automatically injected into every request body.
• There are no deprecated aliases in the Elixir SDK.

Source Of Truth

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