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 with Firecrawl using the Elixir SDK. It is generated from SDK source and OpenAPI spec.

Install

Add to your mix.exs dependencies:

{:firecrawl, "~> 1.10"}

Then run:

mix deps.get

Authenticate

Set the API key in application config:

config :firecrawl, api_key: "fc-YOUR_API_KEY"

Or pass it per-request:

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

Omitting the key uses the keyless free tier (rate-limited per IP).

Per-request options (second keyword list):

Option	Type	Default	Description
api_key	string	Application config or nil	API key override for this request
base_url	string	"https://api.firecrawl.dev/v2"	Base URL override

When To Use What

• search_and_scrape: Use when you start with a query and need to discover relevant pages. Returns ranked results with optional scraping.
• scrape_and_extract_from_url: Use when you already have a URL and want its content in markdown, HTML, JSON, or other formats.
• interact_with_scrape_browser_session: Use when a page needs post-scrape browser actions — clicking, filling forms, running code in the browser sandbox.

Search

Why use it

Search the web for a query and get back ranked results. Optionally scrape each result page inline by passing scrape_options.

Preferred SDK method

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

Bang variant search_and_scrape!/2 raises on error.

Example

{:ok, response} = Firecrawl.search_and_scrape(
  query: "firecrawl web scraping API",
  limit: 5,
  scrape_options: [formats: ["markdown"]]
)

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

Parameters

All parameters are passed as a keyword list. All are optional except query.

Parameter	Type	Description
query	:string	Required. The search query.
limit	:integer	Max results to return.
sources	{:list, :any}	Sources: "web", "news", "images".
categories	{:list, :any}	Filter: "github", "research", "pdf".
include_domains	{:list, :string}	Restrict results to these domains.
exclude_domains	{:list, :string}	Exclude results from these domains.
tbs	:string	Time-based search filter (e.g. "qdr:d" for past day).
location	:string	Location string for geo-targeted results.
country	:string	ISO country code for geo-targeting (e.g. "US").
ignore_invalid_urls	:boolean	Ignore invalid URLs in results.
timeout	:integer	Timeout in milliseconds.
highlights	:boolean	Generate query-relevant highlights. Default: true.
scrape_options	:keyword_list	Scrape options applied to each result page.
enterprise	{:list, :string}	Enterprise options: ["zdr"] or ["anon"].

Returns: {:ok, Req.Response.t()} or {:error, Exception.t()}. The response body contains "data" with "web", "news", and "images" lists.

Scrape

Why use it

Scrape a single URL and get its content as markdown, HTML, structured JSON, screenshots, or other formats.

Preferred SDK method

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

Bang variant scrape_and_extract_from_url!/2 raises on error.

Example

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

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

Parameters

All parameters are passed as a keyword list. All are optional except url.

Parameter	Type	Description
url	:string	Required. The URL to scrape.
formats	{:list, :any}	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "changeTracking", "branding", "product", "menu", "audio", "video".
only_main_content	:boolean	Extract only the main content, excluding headers/navs/footers.
include_tags	{:list, :string}	HTML tags to include in output.
exclude_tags	{:list, :string}	HTML tags to exclude from output.
timeout	:integer	Timeout in milliseconds (default 60000, max 300000).
wait_for	:integer	Delay in ms before fetching content.
mobile	:boolean	Emulate a mobile device.
headers	:any	Custom HTTP headers.
actions	{:list, :any}	Browser actions before scraping.
parsers	{:list, :any}	Parser configs (e.g. "pdf").
location	:keyword_list	Geo-location with country and languages fields.
skip_tls_verification	:boolean	Skip TLS certificate verification.
remove_base64_images	:boolean	Remove base64 images from output.
block_ads	:boolean	Block ads and cookie popups.
proxy	:basic | :enhanced | :auto	Proxy tier.
max_age	:integer	Use cached result if younger than this (ms).
min_age	:integer	Min age for cache-only check (ms).
store_in_cache	:boolean	Store result in Firecrawl cache.
lockdown	:boolean	Serve from cache only.
redact_pii	:boolean	Redact PII from returned content.
audit_metadata	:keyword_list	User attribution for SIEM logging (requires username).
profile	:keyword_list	Persistent browser profile.

Returns: {:ok, Req.Response.t()} or {:error, Exception.t()}. The response body contains "data" with "markdown", "html", "links", "metadata", etc.

Interact

Why use it

Execute code in the browser session of a previous scrape job. Use this for clicking buttons, filling forms, navigating multi-step flows, or running arbitrary JavaScript/Python/Bash in the browser sandbox.

Preferred SDK method

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

Bang variant interact_with_scrape_browser_session!/3 raises on error.

Example

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

job_id = scrape_response.body["data"]["metadata"]["jobId"]

{: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"])

Parameters

Parameter	Type	Description
job_id	String.t()	Required. The scrape job ID (first positional argument).
code	:string	Required. Code to execute in the browser sandbox.
language	:python | :node | :bash	Execution language. Default: :node.
timeout	:integer	Execution timeout in seconds (1–300).

Returns: {:ok, Req.Response.t()} with body containing "success", "stdout", "stderr", "result", "exitCode", "killed", "error".

Stop the session:

Firecrawl.stop_interactive_scrape_browser_session(job_id)

Notes

• All parameter names use snake_case (e.g. only_main_content, skip_tls_verification). The SDK converts them to camelCase JSON keys internally.
• Parameters are passed as keyword lists, not maps.
• The SDK is auto-generated from the OpenAPI spec. Function names match the OpenAPI operation IDs closely.
• The interact_with_scrape_browser_session function only supports code, not prompt (natural-language browser instruction). Use code to execute scripts directly.
• Proxy values are atoms (:basic, :enhanced, :auto), not strings.
• Every function has a bang variant (!) that raises instead of returning {:error, ...}.
• 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