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 source (v1.11.3) and the v2 OpenAPI spec. Function names and parameters match the SDK public API.

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.search_and_scrape(
  [query: "site:docs.firecrawl.dev webhook retries"],
  api_key: "fc-your-api-key"
)

When To Use What

• search: use when you start with a query and need discovery. Returns matching pages you can then scrape.
• scrape: use when you already have a URL and want page content in markdown, HTML, JSON, or other formats.
• 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:, e.g. 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",
  limit: 5
)

Parameters

Parameter	Type	Description
query	string	Search query. Use site:example.com to limit to a domain.
sources	list	Sources: "web", "news", "images", :web, :news, :images. Also accepts maps like %{type: "web"}.
categories	list	Filter: "developer", "research", "pdf", or atom equivalents. Also accepts maps.
include_domains	list of strings	Restrict results to these domains.
exclude_domains	list of strings	Exclude results from these domains.
limit	integer	Cap result count.
tbs	string	Time-based filter, e.g. "qdr:d".
location	string	Localized results.
country	string	ISO country code for geo-targeted results.
ignore_invalid_urls	boolean	Drop URLs that can’t be scraped.
highlights	boolean	Generate query-relevant highlights.
timeout	integer	Request timeout in milliseconds.
scrape_options	keyword list	Scrape each result (same fields as scrape params).
domain_tools	boolean	Include Alexandria domain-matched tools.
tool_detail	atom or string	Detail level: :compact, :summary, :full.
enterprise	list of strings	Enterprise options: ["zdr"] for Zero Data Retention, ["anon"] for anonymized.

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",
    %{type: "json", prompt: "Extract plan names and prices."}
  ],
  only_main_content: true
)

Parameters

Parameter	Type	Description
url	string	Page 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}, etc.
headers	map	Custom request headers.
include_tags	list of strings	Include only these HTML tags.
exclude_tags	list of strings	Exclude these HTML tags.
only_main_content	boolean	Strip nav, footer, boilerplate.
timeout	integer	Timeout in milliseconds.
wait_for	integer	Wait for page render (milliseconds).
mobile	boolean	Use mobile viewport.
parsers	list	File parsing, e.g. [%{type: "pdf", mode: "auto", maxPages: 5}].
actions	list of maps	Pre-scrape browser actions: click, wait, write, press, scroll, scrape, executeJavascript, pdf.
location	keyword list	Geo/language: [country: "US", languages: ["en-US"]].
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 or string	Proxy: :basic, :enhanced, :auto.
max_age	integer	Accept cached data up to this age (ms).
min_age	integer	Accept cached data only if at least this old (ms).
store_in_cache	boolean	Cache the result.
lockdown	boolean	Serve only cached results.
profile	keyword list	Persistent browser profile: [name: "my-session", save_changes: true].
zero_data_retention	boolean	Enable zero data retention.
domain_tools	boolean	Include Alexandria domain-matched tools.

Interact

Why use it

Control the browser session tied to a scrape job. The Elixir SDK supports code-based interactions (no prompt parameter on the scrape-bound interact).

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
)

# End the session when done:
{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session("<scrapeJobId>")

Parameters

Parameter	Type	Description
job_id	string	Scrape job ID.
code	string	Code to run in the browser session.
language	atom or string	Runtime: :python, :node, :bash.
timeout	integer	Execution timeout in seconds.

Stop session: Firecrawl.stop_interactive_scrape_browser_session(job_id) ends the browser session.

Standalone interact sessions

The Elixir SDK also exposes standalone interact sessions (not tied to a scrape):

• Firecrawl.create_browser_session(params, opts) — create a standalone session with ttl, activity_ttl, stream_web_view, profile.
• Firecrawl.execute_browser_code(session_id, params, opts) — execute code with code, language, timeout.
• Firecrawl.delete_browser_session(session_id, opts) — destroy the session.
• Firecrawl.list_browser_sessions(params, opts) — list sessions, optionally filtered by status (:active, :destroyed).

Notes

• The Elixir client is auto-generated from the OpenAPI spec. Function names are OpenAPI operation IDs converted to snake_case.
• Every function has a bang (!) variant that raises on error instead of returning {:error, _}.
• Snake_case params are automatically converted to camelCase for the JSON API body.
• This SDK exposes code-based interactions only on the scrape-bound endpoint (no prompt parameter on interact_with_scrape_browser_session).

Source Of Truth

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