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.9.1, firecrawl/apps/elixir-sdk) and the v2 OpenAPI 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: "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.
• 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. 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",
  sources: [:web, :news],
  limit: 10,
  scrape_options: [
    formats: ["markdown"],
    only_main_content: true
  ]
)

Parameters

Parameter	Type	Use when
query	string (required)	You need a search query. Use site:example.com to scope.
sources	list of atoms or strings	You want to control sources. Values: :web, :news, :images. Default: [:web].
categories	list of atoms, strings, or maps	You want to filter by category. Values: :github, :research, :pdf.
include_domains	list of strings	You want results only from specific domains.
exclude_domains	list of strings	You want to exclude specific domains.
limit	integer	You want to cap results.
tbs	string	You need a time filter (e.g. qdr:d, qdr:w).
location	string	You want localized results.
country	string	You want ISO 3166-1 alpha-2 targeting (e.g. "US").
ignore_invalid_urls	boolean	You want to drop URLs that cannot be scraped.
timeout	integer	You need a request timeout in milliseconds.
highlights	boolean	You want query-relevant highlights. Default: true.
scrape_options	keyword list	You want to scrape each search result inline.
enterprise	list of strings	You need enterprise controls. 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://example.com/pricing",
  formats: [
    "markdown",
    "links",
    %{type: "json", prompt: "Extract plan names and prices."}
  ],
  only_main_content: true,
  wait_for: 1000
)

Parameters

Parameter	Type	Use when
url	string (required)	You want to scrape a specific page.
formats	list of strings or maps	You want multiple output formats. See format types below.
headers	map	You need custom request headers.
include_tags	list of strings	You want to include only specific HTML tags.
exclude_tags	list of strings	You want to exclude specific HTML tags.
only_main_content	boolean	You want to strip nav, footer, and boilerplate.
timeout	integer	You need a timeout in milliseconds. Default: 60000. Min: 1000. Max: 300000.
wait_for	integer	You need to wait for page render (milliseconds).
mobile	boolean	You want a mobile viewport.
parsers	list of strings or maps	You need file parsing controls.
actions	list of maps	You need pre-scrape browser actions.
location	keyword list	You need geo or language-aware scraping.
skip_tls_verification	boolean	You need to skip TLS verification.
remove_base64_images	boolean	You want to drop base64 images from markdown.
block_ads	boolean	You want ad and cookie popup blocking.
proxy	atom	You need proxy control. Values: :basic, :enhanced, :auto.
max_age	integer	You want cached data up to a maximum age (ms). Default: 2 days.
min_age	integer	You want cached data only if at least this old (ms).
store_in_cache	boolean	You want Firecrawl to cache the result.
lockdown	boolean	You want only cached results, no outbound requests.
redact_pii	boolean	You want PII redacted from content.
audit_metadata	keyword list	You need user attribution for SIEM. Key: username (required).
profile	keyword list	You want a persistent browser profile. Keys: name, save_changes.
zero_data_retention	boolean	You want zero data retention for this scrape.

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

Format maps: %{type: "json", prompt: ...}, %{type: "screenshot", fullPage: true}, %{type: "changeTracking", modes: ["git-diff"]}

Action types: wait, click, write, press, scroll, screenshot, scrape, executeJavascript, pdf

Interact

Why use it

Use interact when a page requires browser actions or code execution after a scrape starts. 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 = get_in(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
)

Parameters

Parameter	Type	Use when
job_id	string	You have a scrape job ID.
code	string (required)	You want to run code in the browser session.
language	atom or string	You need a specific runtime. Values: :python, :node, :bash.
timeout	integer	You need an execution timeout in seconds.

Stop session

Firecrawl.stop_interactive_scrape_browser_session(job_id) → ends the browser session. A bang variant stop_interactive_scrape_browser_session!/2 is also available.

Notes

• The Elixir client is OpenAPI-shaped; function names and parameter keys are generated from the spec.
• Each 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).
• Pass api_key: in opts to override the configured key per call.

Source Of Truth

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