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 via the official Elixir SDK. It is generated from SDK source and the OpenAPI spec. The Elixir SDK is auto-generated from the OpenAPI spec and uses function names that mirror operation IDs.

Install

Add to your mix.exs dependencies:

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

Authenticate

Configure in config/config.exs:

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

Or pass api_key as an option to any function call:

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

When To Use What

• search_and_scrape — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
• scrape_and_extract_from_url — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
• interact_with_scrape_browser_session / execute_browser_code — Use when a page needs browser automation — clicks, form fills, or post-scrape dynamic content extraction.

Search

Why use it

Search the web for a query and get results with titles, URLs, descriptions, and optionally full page content. Supports filtering by domain, time range, category, and source type.

Preferred SDK function

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

Example

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

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

Parameters

All parameters are passed as a keyword list. Keys use snake_case and are automatically mapped to camelCase for the API.

Parameter	Type	Description
query	:string	The search query (max 500 chars). Required.
limit	:integer	Max results to return per source type. Default: 10 (API). Range: 1–100.
sources	list	Source types: "web", "news", "images", "alexandria". Default: ["web"].
categories	list	Filter by category: "github", "research", "pdf", "developer", "gov".
include_domains	list(string)	Restrict results to these domains. Cannot combine with exclude_domains.
exclude_domains	list(string)	Exclude results from these domains.
tbs	:string	Time-based filter. E.g. "qdr:d" for past day, "sbd:1,qdr:w" for sorted by date in past week.
location	:string	Location for search results.
country	:string	ISO 3166-1 alpha-2 country code.
highlights	:boolean	Return query-relevant highlights.
timeout	:integer	Timeout in milliseconds.
ignore_invalid_urls	:boolean	Skip invalid URLs instead of failing.
safe	:boolean	Enable safe search.
scrape_options	:keyword_list	Apply scrape options to each result page.
domain_tools	:boolean	Include Alexandria tool contracts matched to result domains.
tool_detail	:compact | :summary | :full	Detail level for tool contracts. Default: "compact".
enterprise	list(string)	Enterprise options: "default", "anon", "zdr".

Bang variant

Firecrawl.search_and_scrape!(params, opts) — raises on error instead of returning {:error, ...}.

Scrape

Why use it

Scrape a URL and get its content in your chosen format — markdown, HTML, JSON (with schema-based extraction), screenshots, and more. Supports browser actions, caching, proxies, and PDF parsing.

Preferred SDK function

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

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

Parameter	Type	Description
url	:string	The URL to scrape. Required.
formats	list	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "json", "summary", "audio", "video", "changeTracking", "branding", "product", "menu". Default: ["markdown"]. Some accept config maps.
only_main_content	:boolean	Strip headers, navs, footers. Default: true (API).
only_clean_content	:boolean	LLM-based boilerplate removal. Default: false.
include_tags	list(string)	Only include content from these HTML tags.
exclude_tags	list(string)	Exclude content from these HTML tags.
headers	any	Custom HTTP headers.
wait_for	:integer	Extra delay in ms before fetching content. Default: 0.
timeout	:integer	Request timeout in ms. Default: 60000, max: 300000.
mobile	:boolean	Emulate a mobile device. Default: false.
max_age	:integer	Use cached result if younger than this (ms). Default: 172800000 (2 days).
min_age	:integer	Cache-only mode.
store_in_cache	:boolean	Cache this scrape result.
actions	list	Browser actions before scraping.
location	:keyword_list	Geolocation config.
parsers	list	File parsers. Default: ["pdf"].
proxy	:basic | :enhanced | :auto | string	Proxy type.
skip_tls_verification	:boolean	Skip TLS verification. Default: true (API).
remove_base64_images	:boolean	Strip base64 images from output.
block_ads	:boolean	Block ads and cookie popups.
lockdown	:boolean	Serve only cached results.
check_prompt_injection	:boolean	Scan for prompt injection (adds 4 credits).
redact_pii	any	Redact PII.
profile	:keyword_list	Persistent browser profile.
zero_data_retention	:boolean	Enable zero data retention.
alexandria	any	Alexandria tool execution.
domain_tools	:boolean	Return Alexandria tool contracts.

Bang variant

Firecrawl.scrape_and_extract_from_url!(params, opts) — raises on error.

Interact

Why use it

The Elixir SDK supports two interact patterns:

1. Post-scrape interaction — After scraping a page, interact with its browser session using interact_with_scrape_browser_session/3.
2. Standalone browser session — Create an independent browser session with create_browser_session/2, then execute code with execute_browser_code/3.

Preferred SDK functions

Post-scrape interaction:

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

Standalone browser session:

Firecrawl.create_browser_session(params, opts \\ [])
Firecrawl.execute_browser_code(session_id, params, opts \\ [])

Example — Post-scrape interaction

{:ok, scrape} = Firecrawl.scrape_and_extract_from_url(url: "https://example.com")
scrape_id = scrape.body["data"]["metadata"]["scrapeId"]

{:ok, response} = Firecrawl.interact_with_scrape_browser_session(scrape_id,
  code: "document.title",
  language: :node
)

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

Firecrawl.stop_interactive_scrape_browser_session(scrape_id)

Example — Standalone browser session

{:ok, session} = Firecrawl.create_browser_session(ttl: 300)
session_id = session.body["data"]["sessionId"]

{:ok, response} = Firecrawl.execute_browser_code(session_id,
  code: ~s(await page.goto("https://example.com"); document.title),
  language: :node
)

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

Firecrawl.delete_browser_session(session_id)

Post-scrape interaction parameters

Parameter	Type	Description
job_id	String.t()	The scrape job ID from a previous scrape. Required (positional).
code	:string	Code to execute in the browser sandbox. Required. Max 100,000 chars.
language	:python | :node | :bash	Language for code execution. Default: "node" (API).
timeout	:integer	Execution timeout in seconds. Min: 1, default: 30 (API), max: 300.
origin	:string	Origin label for telemetry.

Standalone browser session parameters

create_browser_session:

Parameter	Type	Description
ttl	:integer	Total session TTL in seconds. Default: 300. Range: 30–3600.
activity_ttl	:integer	Inactivity timeout in seconds. Range: 10–3600.
stream_web_view	:boolean	Stream a live browser view. Default: true.
block_ads	:boolean	Block ads and cookie popups. Default: true.
profile	:keyword_list	Persistent storage profile.
location	:keyword_list	Country: [country: "GB"].

execute_browser_code:

Parameter	Type	Description
session_id	String.t()	The session ID. Required (positional).
code	:string	Code to execute. Required.
language	:python | :node | :bash	Language. Default: "node" (API).
timeout	:integer	Timeout in seconds.

Stopping sessions

• Post-scrape: Firecrawl.stop_interactive_scrape_browser_session(job_id)
• Standalone: Firecrawl.delete_browser_session(session_id)

Notes

• No deprecated aliases exist in the Elixir SDK.
• Naming style: All parameters use snake_case. The SDK auto-maps to camelCase for the API.
• Function names are OpenAPI-derived. They mirror operation IDs exactly (e.g. scrape_and_extract_from_url, not scrape).
• Return type: All functions return {:ok, Req.Response.t()} | {:error, Exception.t()}. Use bang variants (!) to raise on error.
• Package name: :firecrawl (Hex.pm).
• Base URL: Defaults to https://api.firecrawl.dev/v2. Override with base_url option.
• Dependencies: req ~> 0.5, nimble_options ~> 1.1.

Source Of Truth

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