Elixir Agent Quickstart

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

Canonical Firecrawl Elixir quickstart for agents. Generated from SDK source (:firecrawl v1.11.0) and the v2 OpenAPI spec. The Elixir client is auto-generated from the OpenAPI spec; function names and parameter keys reflect this.

Install

Add to mix.exs:

{:firecrawl, "~> 1.11"}

Authenticate

# config/runtime.exs or config.exs
config :firecrawl, api_key: System.get_env("FIRECRAWL_API_KEY")

# Or pass api_key per call:
{:ok, res} = Firecrawl.scrape_and_extract_from_url(
  [url: "https://example.com"],
  api_key: "fc-your-api-key"
)

All functions accept an optional trailing opts keyword list supporting :api_key and :base_url overrides.

When To Use What

• search: use when you start with a query and need discovery.
• scrape: use when you already have a URL and want page content.
• interact: use when the page needs code execution in a scrape-bound browser session. Requires a scrape job ID from a prior scrape.

Search

Why use it

Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with site: in the query string.

Preferred SDK method

Firecrawl.search_and_scrape(params \\ [], opts \\ []) → {:ok, map()} | {:error, Firecrawl.Error.t()}

Example

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

# Results in res["data"]["web"], res["data"]["news"], res["data"]["images"]

Parameters

Parameter	Type	Description
query	string (required)	Search query. Use site:example.com to scope to a domain.
sources	list	Sources: :web, :news, :images (atoms or strings).
categories	list	Filter results: :developer, :research, :pdf (atoms or strings).
include_domains	list(string)	Restrict results to these domains.
exclude_domains	list(string)	Exclude results from these domains.
limit	integer	Max results.
tbs	string	Time-based filter (e.g. qdr:d, qdr:w).
location	string	Location string for localized results.
country	string	ISO 3166-1 alpha-2 country code (e.g. "US").
ignore_invalid_urls	boolean	Drop URLs that cannot be scraped.
timeout	integer	Request timeout in milliseconds.
highlights	boolean	Generate query-relevant highlights. Defaults to true.
scrape_options	keyword	Scrape each search result (see Scrape parameters).
enterprise	list(string)	Enterprise options: ["zdr"] for Zero Data Retention, ["anon"] for anonymized search.

Scrape

Why use it

Get structured content from a URL in one or more formats.

Preferred SDK method

Firecrawl.scrape_and_extract_from_url(params \\ [], opts \\ []) → {:ok, map()} | {:error, Firecrawl.Error.t()}

Example

{:ok, res} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com/pricing",
  formats: [
    "markdown",
    "links",
    %{type: "json", prompt: "Extract plan names and prices."}
  ],
  only_main_content: true,
  wait_for: 1000
)

Parameters

Parameter	Type	Description
url	string (required)	The URL to scrape.
formats	list	Output formats. Strings: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "json", "branding", "audio", "video". Maps: %{type: "json", prompt: ..., schema: ...}, %{type: "screenshot", fullPage: true}, %{type: "changeTracking", modes: ["git-diff"]}.
headers	map	Custom HTTP headers.
include_tags	list(string)	Only include content from these HTML tags.
exclude_tags	list(string)	Exclude content from these HTML tags.
only_main_content	boolean	Strip nav, footer, and boilerplate.
timeout	integer	Timeout in milliseconds. Min 1000, default 60000, max 300000.
wait_for	integer	Wait for page to render (milliseconds).
mobile	boolean	Use a mobile viewport.
parsers	list	File parsers: %{type: "pdf", mode: "auto", maxPages: 5}.
actions	list(map)	Pre-scrape browser actions: wait, click, write, press, scroll, screenshot, scrape, executeJavascript, pdf.
location	keyword	[country: "US", languages: ["en-US"]] for geo-aware scraping.
skip_tls_verification	boolean	Skip TLS verification.
remove_base64_images	boolean	Drop base64 images from markdown.
block_ads	boolean	Block ads and cookie popups.
proxy	atom	:basic, :enhanced, :auto.
max_age	integer	Accept cached data up to this age (milliseconds).
min_age	integer	Accept cached data only if at least this old (milliseconds).
store_in_cache	boolean	Cache the result.
lockdown	boolean	Serve only previously cached results; never make outbound requests.
redact_pii	boolean	Redact personally identifiable information.
profile	keyword	Persistent browser profile: [name: "...", save_changes: true].
audit_metadata	keyword	User attribution for SIEM logging: [username: "..."].
zero_data_retention	boolean	Enable zero data retention for this scrape.

Interact

Why use it

Execute code in the browser session tied to a scrape job. The Elixir SDK supports code-based interactions only (no prompt parameter).

Preferred SDK method

Firecrawl.interact_with_scrape_browser_session(job_id, params \\ [], opts \\ []) → {:ok, map()} | {:error, Firecrawl.Error.t()}

Example

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

job_id = get_in(scrape_res, ["data", "metadata", "scrapeId"])

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

# Stop the session when done
{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session(job_id)

Parameters

Parameter	Type	Description
job_id	string (required, path)	Scrape job ID from scrape response metadata.
code	string (required)	Code to execute in the browser session.
language	atom	Runtime: :python, :node, :bash.
timeout	integer	Execution timeout in seconds.

Firecrawl.stop_interactive_scrape_browser_session(job_id) ends the browser session.

Notes

• The Elixir client is auto-generated from the OpenAPI spec; function names follow the spec operation IDs.
• Each function has a bang (!) variant that raises on error: e.g. search_and_scrape!/2, scrape_and_extract_from_url!/2.
• This SDK exposes code-based interactions only — there is no prompt parameter (unlike Node.js, Python, and Rust SDKs).
• No deprecated aliases exist in the Elixir SDK.
• The proxy parameter uses atoms (:basic, :enhanced, :auto) rather than strings.

Source Of Truth

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