Elixir Agent Quickstart

Canonical Firecrawl Elixir quickstart for external agents using search, scrape, and interact.

Firecrawl Elixir Agent Quickstart

Canonical quickstart for external agents. Generated from :firecrawl hex package v1.11.0 source (firecrawl/apps/elixir-sdk) and the v2 OpenAPI spec. Function names are auto-generated from the OpenAPI spec; parameters use snake_case and are converted to camelCase for the API.

Install

# mix.exs
defp deps do
  [
    {:firecrawl, "~> 1.11"}
  ]
end

Authenticate

# Option 1: Application config
# config/config.exs
config :firecrawl, api_key: "fc-your-api-key"

# Option 2: Per-call option
Firecrawl.search_and_scrape([query: "test"], api_key: "fc-your-api-key")

Additional per-call options: base_url (override default https://api.firecrawl.dev/v2), plus any keyword passed through to Req.

When To Use What

• search_and_scrape — start with a query, discover relevant pages, then scrape or interact with the results.
• scrape_and_extract_from_url — you already have a URL and want structured page content.
• interact_with_scrape_browser_session — the page needs code execution in a post-scrape browser session.

Search

Why use it

Discover relevant pages from a text query. Supports site: scoping, source filtering, category narrowing, and inline scraping of results.

Preferred SDK function

Firecrawl.search_and_scrape(params, opts \\ []) → {:ok, %Req.Response{}} or {:error, exception}

Bang variant: Firecrawl.search_and_scrape!(params, opts) → %Req.Response{} or raises.

Example

{:ok, response} = Firecrawl.search_and_scrape(
  query: "site:docs.firecrawl.dev webhook retries",
  sources: ["web"],
  limit: 5,
  scrape_options: [formats: ["markdown"], only_main_content: true]
)

web_results = response.body["data"]["web"] || []
Enum.each(web_results, fn hit ->
  IO.puts("#{hit["url"]} #{hit["title"]}")
end)

Parameters

First argument (keyword list):

Parameter	Type	Description
query	:string	Search query (required). Use site:example.com to limit by domain.
sources	{:list, :any}	Sources: "web", "news", "images".
categories	{:list, :any}	Filter by category.
include_domains	{:list, :string}	Only include these domains.
exclude_domains	{:list, :string}	Exclude these domains.
limit	:integer	Max results.
tbs	:string	Time-based filter (e.g. "qdr:d").
location	:string	Geographic location.
country	:string	ISO country code.
ignore_invalid_urls	:boolean	Drop unscrappable URLs.
timeout	:integer	Timeout in milliseconds.
highlights	:boolean	Query-relevant highlights (default true).
scrape_options	:keyword_list	Scrape each result (see Scrape parameters).
enterprise	{:list, :string}	ZDR options: ["zdr"] or ["anon"].

Scrape

Why use it

Get structured content from a URL in one or more formats: markdown, HTML, JSON extraction, screenshots, and more.

Preferred SDK function

Firecrawl.scrape_and_extract_from_url(params, opts \\ []) → {:ok, %Req.Response{}} or {:error, exception}

Bang variant: Firecrawl.scrape_and_extract_from_url!(params, opts) → %Req.Response{} or raises.

Example

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

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

Parameters

First argument (keyword list):

Parameter	Type	Description
url	:string	URL to scrape (required).
formats	{:list, :any}	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "json", "audio", "video", etc.
headers	:any	Custom HTTP headers.
include_tags	{:list, :string}	Include only these HTML tags.
exclude_tags	{:list, :string}	Exclude these HTML tags.
only_main_content	:boolean	Strip nav, footer, boilerplate.
timeout	:integer	Timeout in ms (default 60000, max 300000).
wait_for	:integer	Wait for page render (ms).
mobile	:boolean	Use mobile viewport.
parsers	{:list, :any}	File parsing controls (e.g. PDF).
actions	{:list, :any}	Pre-scrape browser actions.
location	:keyword_list	Geo/language: [country: "US", languages: ["en-US"]].
skip_tls_verification	:boolean	Skip TLS verification.
remove_base64_images	:boolean	Drop base64 images.
block_ads	:boolean	Block ads and cookie popups.
proxy	:basic | :enhanced | :auto	Proxy type.
max_age	:integer	Cached data max age (ms, default 2 days).
min_age	:integer	Cache-only mode, min age (ms).
store_in_cache	:boolean	Cache the result.
lockdown	:boolean	Only serve cached results.
redact_pii	:boolean	Redact PII.
audit_metadata	:keyword_list	SIEM logging: [username: "agent-1"].
profile	:keyword_list	Persistent browser profile: [name: "session", save_changes: true].

Interact

Why use it

Execute code in the browser session tied to a scrape job for post-scrape automation.

Preferred SDK function

Firecrawl.interact_with_scrape_browser_session(job_id, params, opts \\ []) → {:ok, %Req.Response{}} or {:error, exception}

Bang variant: Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts) → %Req.Response{} or raises.

Example

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

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

{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
  code: "console.log(await page.title());",
  language: :node
)

IO.puts(result.body["stdout"])

# Stop the session:
Firecrawl.stop_interactive_scrape_browser_session(job_id)

Parameters

First argument: job_id (String.t) — scrape job ID.

Second argument (keyword list):

Parameter	Type	Description
code	:string	Code to execute in the browser session (required).
language	:python | :node | :bash	Runtime for code execution.
timeout	:integer	Execution timeout in seconds.
origin	:string	Origin label for telemetry.

Stop session

Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ []) → {:ok, %Req.Response{}} or {:error, exception}

Notes

• Function names are auto-generated from the OpenAPI spec, so they are verbose: search_and_scrape, scrape_and_extract_from_url, interact_with_scrape_browser_session.
• Every function has a bang (!) variant that raises on error.
• Parameters use snake_case keys; they are converted to camelCase for the JSON body automatically.
• The last argument to every function is always opts \\ [] for :api_key, :base_url, and Req pass-through options.
• Responses are raw %Req.Response{} structs; access data via response.body["data"].
• The Elixir SDK’s interact_with_scrape_browser_session requires code; it does not support prompt-based natural-language interaction.
• Parameters are validated at call time by NimbleOptions.

Source Of Truth

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