Elixir Agent Quickstart

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

Canonical Firecrawl Elixir quickstart for external agents. Aligned with :firecrawl hex package v1.9.1 (firecrawl/apps/elixir-sdk) and the v2 OpenAPI spec. The Elixir client is OpenAPI-generated; function names and parameter keys come directly from the spec.

Install

Add to mix.exs:

{:firecrawl, "~> 1.9"}

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.search_and_scrape([query: "example"], api_key: "fc-your-api-key")

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

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. You can constrain results to a site with site:, for example site:docs.firecrawl.dev crawl webhooks.

Preferred SDK method

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

Example

{:ok, res} = Firecrawl.search_and_scrape(query: "site:docs.firecrawl.dev webhook retries")

Parameters

Parameter	Type	Description
query	string (required)	The search query. Use site:example.com to limit results to a domain.
sources	list	Sources to search. Values: "web", "news", "images", or atoms :web, :news, :images.
categories	list	Filter by category. Values: "github", "research", "pdf", or atoms.
include_domains	list(string)	Restrict results to these domains.
exclude_domains	list(string)	Exclude these domains.
limit	integer	Cap 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 list	Scrape each search result (see Scrape parameters).
enterprise	list(string)	Enterprise options. Values: "zdr", "anon".

Scrape

Why use it

Use scrape when you already have a URL and want structured content 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://docs.firecrawl.dev",
  formats: ["markdown"]
)

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: "..."}, %{type: "screenshot", fullPage: true}, %{type: "changeTracking", modes: ["git-diff"]}.
headers	map	Custom request headers.
include_tags	list(string)	Include only specific HTML tags.
exclude_tags	list(string)	Exclude specific HTML tags.
only_main_content	boolean	Strip nav, footer, and other boilerplate.
timeout	integer	Timeout in milliseconds. Min: 1000, default: 60000, max: 300000.
wait_for	integer	Wait for the page to render (milliseconds).
mobile	boolean	Use a mobile viewport.
parsers	list	File parsing controls. Values: "pdf", %{type: "pdf", mode: "auto", maxPages: 5}.
actions	list(map)	Pre-scrape browser actions. Types: wait, screenshot, click, write, press, scroll, scrape, executeJavascript, pdf.
location	keyword list	Geo or language-aware scraping. Keys: country:, languages:.
skip_tls_verification	boolean	Skip TLS verification.
remove_base64_images	boolean	Drop base64 images from markdown output.
block_ads	boolean	Block ads and cookie popups.
proxy	atom	Proxy mode. Values: :basic, :enhanced, :auto.
max_age	integer	Use cached data up to this age (milliseconds).
min_age	integer	Use cached data only if at least this old (milliseconds).
store_in_cache	boolean	Cache the result.
lockdown	boolean	Only serve cached results, never make an outbound request.
redact_pii	boolean	Redact personally identifiable information.
profile	keyword list	Persistent browser profile. Keys: name:, save_changes:.
zero_data_retention	boolean	Enable zero data retention for this scrape.
audit_metadata	keyword list	User attribution for SIEM logging. Key: username: (required).

Interact

Why use it

Use interact when a page requires browser actions or code execution after a scrape starts.

Preferred SDK method

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

Example

{:ok, res} = Firecrawl.interact_with_scrape_browser_session(
  "<scrapeJobId>",
  code: "console.log(await page.title());",
  language: :node,
  timeout: 60
)

Parameters

Parameter	Type	Description
job_id	string	Scrape job ID. First positional argument.
code	string (required)	Code to execute in the browser session.
language	atom | string	Runtime. Values: :python, :node, :bash.
timeout	integer	Execution timeout in seconds.
origin	string	Optional origin label for telemetry.

Stop session

Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ []) issues DELETE /scrape/{jobId}/interact.

{:ok, res} = Firecrawl.stop_interactive_scrape_browser_session("<scrapeJobId>")

Notes

• The Elixir SDK is OpenAPI-generated; function names come from the spec and are not renamed.
• Every public function has a bang (!) variant that raises on error instead of returning {:error, _}.
• This SDK exposes code-based interactions only (no prompt parameter on interact_with_scrape_browser_session).
• Per-request options (like api_key:, base_url:) are passed via the trailing opts keyword list.

Source Of Truth

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