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 1.9.2) 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:

defp deps do
  [
    {:firecrawl, "~> 1.9"}
  ]
end

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

There is no client struct. The SDK builds a Req client per request. Configuration is global (via config :firecrawl) or per-request (via the trailing opts keyword list).

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: in the query.

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],
  limit: 5,
  scrape_options: [
    formats: ["markdown"],
    only_main_content: true
  ]
)

Parameters

• query — string (required). The search query. Use site:example.com to limit to a domain.
• sources — list of atoms/strings. Values: :web, :news, :images.
• categories — list of atoms/strings. Values: :github, :research, :pdf.
• include_domains — list of strings. Restrict results to these domains.
• exclude_domains — list of strings. Exclude results from these domains.
• limit — integer. Max number of results.
• tbs — string. Time-based filter (e.g. "qdr:d", "qdr:w", "qdr:m").
• location — string. Localized search results.
• country — string. ISO 3166-1 alpha-2 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.
• enterprise — list of strings. Enterprise ZDR options: ["zdr"] for end-to-end, ["anon"] for anonymized.
• scrape_options — keyword list. Scrape each search 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",
    %{type: "json", prompt: "Extract plan names and prices."}
  ],
  only_main_content: true
)

Parameters

• url — string (required). The URL to scrape.
• formats — list of format strings or format maps. Output formats.
  • Strings: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "json", "branding", "audio", "video"
  • Maps: %{type: "json", prompt: ..., schema: ...}, %{type: "question", question: ...}, %{type: "highlights", query: ...}, %{type: "screenshot", fullPage: ..., quality: ..., viewport: ...}, %{type: "changeTracking", modes: [...], tag: ...}, %{type: "attributes", selectors: [%{selector: ..., attribute: ...}]}
• headers — map. Custom HTTP headers.
• include_tags — list of strings. Only include these HTML tags.
• exclude_tags — list of strings. Exclude these HTML tags.
• only_main_content — boolean. Strip nav, footer, and boilerplate.
• timeout — integer. Timeout in milliseconds. Default 60000, max 300000.
• wait_for — integer. Wait for page render in milliseconds.
• mobile — boolean. Use mobile viewport.
• parsers — list. Parser configuration (e.g. ["pdf"] or [%{type: "pdf", mode: "auto", maxPages: 5}]).
• actions — list of action maps. Browser actions before scraping.
  • Types: wait (milliseconds or selector), click (selector, optional all), write (text), press (key), scroll (direction), screenshot, scrape, executeJavascript (script), pdf
• location — keyword list with country: and languages:. Geo or language-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, or :auto.
• max_age — integer. Serve cached data up to this age in milliseconds.
• min_age — integer. Serve cached data only if at least this old in milliseconds.
• store_in_cache — boolean. Cache the result.
• lockdown — boolean. Serve only cached results; never make outbound requests.
• redact_pii — boolean. Redact personally identifiable information.
• audit_metadata — keyword list with username:. User attribution for SIEM logging.
• profile — keyword list with name: and optional save_changes:. Persistent browser profile.
• zero_data_retention — boolean. Enable zero data retention.

Interact

Why use it

Control the browser session tied to a scrape job — run code in the browser. 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
)

# When done:
{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session(job_id)

Parameters

• job_id — string (required, first argument). Scrape job ID.
• code — string (required). Code to execute in the browser session.
• language — atom. :python, :node, or :bash.
• timeout — integer. Execution timeout in seconds.

Stop the session with Firecrawl.stop_interactive_scrape_browser_session(job_id).

Notes

• The Elixir SDK is auto-generated from the OpenAPI spec. Function names come directly from spec operation IDs.
• Every function has a bang (!) variant (e.g. search_and_scrape!) that raises on error instead of returning {:error, _}.
• Snake_case parameter keys are automatically converted to camelCase JSON keys.
• Atoms for enum values (:basic, :node) are converted to strings before sending.
• Parameters are validated at call time using NimbleOptions.
• No client struct — a fresh Req client is created per request.

Source Of Truth

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