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 SDK source (firecrawl hex package v1.11.0) and the v2 OpenAPI spec. The Elixir client is auto-generated from the OpenAPI spec; function names match the spec operation IDs.

Install

Add to mix.exs:

{:firecrawl, "~> 1.11"}

Authenticate

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

# Or pass per-call:
{:ok, res} = Firecrawl.search_and_scrape([query: "example"], api_key: "fc-your-api-key")

Every function accepts a trailing opts keyword list with :api_key and :base_url (default https://api.firecrawl.dev/v2) overrides. Scrape, search, and interact work without an API key (keyless free tier, rate-limited by IP).

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 clicks, forms, or post-scrape browser actions.

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

Preferred SDK method

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

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
  ]
)

Parameters

Parameter	Type	Description
query	string	Search query. Required.
sources	list	:web, :news, :images (atoms or strings or maps). Default ["web"].
categories	list	:developer, :research, :pdf (atoms or strings or maps).
include_domains	list(string)	Restrict to these domains.
exclude_domains	list(string)	Exclude these domains.
limit	integer	Max results.
tbs	string	Time-based filter (e.g. qdr:d, qdr:w).
location	string	Localized results.
country	string	ISO country code for geo-targeting.
ignore_invalid_urls	boolean	Drop invalid URLs.
timeout	integer	Timeout in milliseconds.
highlights	boolean	Query-relevant highlights. Default true.
enterprise	list(string)	["zdr"] or ["anon"] for zero data retention.
scrape_options	keyword list	Scrape each result. See Scrape parameters.

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 \\ [])

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,
  actions: [
    %{type: "click", selector: "#accept"},
    %{type: "wait", milliseconds: 750},
    %{type: "scrape"}
  ]
)

Parameters

Parameter	Type	Description
url	string	URL to scrape. Required.
formats	list	Format strings or format maps. See format types below.
headers	map	Custom request headers.
include_tags	list(string)	Only include specific HTML tags.
exclude_tags	list(string)	Exclude specific HTML tags.
only_main_content	boolean	Strip nav, footer, boilerplate.
timeout	integer	Timeout in milliseconds. Default 60000.
wait_for	integer	Wait for page render (milliseconds).
mobile	boolean	Mobile viewport.
parsers	list	"pdf" or %{type: "pdf", mode: "auto", maxPages: 5}.
actions	list(map)	Pre-scrape actions: wait, screenshot, click, write, press, scroll, scrape, executeJavascript, pdf.
location	keyword list	[country: "US", languages: ["en-US"]].
skip_tls_verification	boolean	Skip TLS verification.
remove_base64_images	boolean	Drop base64 images from markdown.
block_ads	boolean	Ad and cookie popup blocking.
proxy	atom	:basic, :enhanced, :auto.
max_age	integer	Max age of cached data (milliseconds). Default 2 days.
min_age	integer	Minimum age of cached data (milliseconds).
store_in_cache	boolean	Cache the result.
lockdown	boolean	Serve only cached results.
redact_pii	boolean	Redact PII from content.
profile	keyword list	[name: "session-name", save_changes: true]. Persistent browser profile.
audit_metadata	keyword list	[username: "..."] for SIEM logging.
zero_data_retention	boolean	Enable zero data retention.

Format strings: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "json", "branding", "audio", "video".

Format maps:

• %{type: "json", prompt: "...", schema: %{...}}
• %{type: "question", question: "..."}
• %{type: "highlights", query: "..."}
• %{type: "screenshot", fullPage: true, quality: 80, viewport: %{width: 1280, height: 720}}
• %{type: "changeTracking", modes: ["git-diff"], tag: "..."}

Interact

Why use it

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

Preferred SDK method

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

Example

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

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

{:ok, res} = 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	Scrape job ID (positional first argument).
code	string	Code to execute in the browser session. Required.
language	atom	:python, :node, :bash.
timeout	integer	Execution timeout in seconds.
origin	string	Optional origin label for telemetry.

Notes

• The Elixir client is auto-generated from the OpenAPI spec via mix run generate.exs.
• Every function has a bang (!) variant: scrape_and_extract_from_url!/2 raises on error instead of returning {:error, _}.
• Parameters are snake_case keyword lists, auto-converted to camelCase for the JSON body.
• Atoms are accepted for enum values (:basic, :node, etc.) and auto-stringified.
• origin is auto-injected as "elixir-sdk@<version>" when not set.
• This SDK exposes code-based interactions only — there is no prompt parameter on the interact function (unlike Node.js, Python, and Rust SDKs).

Source Of Truth

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