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:

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

Then run:

mix deps.get

Authenticate

Configure the API key in your application config:

# config/config.exs
config :firecrawl, api_key: "fc-YOUR_API_KEY"

Or pass the API key per-call via the opts keyword list:

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:

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

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

Bang variant search_and_scrape!/2 raises on error instead of returning {:error, ...}.

Example

{: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

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
)

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: "[e-mail]"].
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

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

Bang variant interact_with_scrape_browser_session!/3 raises on error.

Example

# 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