​

Firecrawl Elixir Agent Quickstart

​

Install

{:firecrawl, "~> 1.11"}

​

Authenticate

# config/runtime.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 webhooks"],
  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

​

Preferred SDK method

​

Example

{:ok, res} = Firecrawl.search_and_scrape(
  query: "site:docs.firecrawl.dev webhook retries",
  limit: 10,
  scrape_options: [
    formats: ["markdown"],
    only_main_content: true
  ]
)

​

Parameters

• query
  • Type: string (required)
  • The search query. Use site:example.com to limit results to a domain.
• sources
  • Type: list of atoms, strings, or maps
  • Which sources to search. Values: :web, :news, :images (or string equivalents, or %{type: "web"}).
• categories
  • Type: list of atoms, strings, or maps
  • Filter by category. Values: :developer, :research, :pdf (or string equivalents).
• include_domains
  • Type: list of strings
  • Restrict results to these domains. Cannot be used with exclude_domains.
• exclude_domains
  • Type: list of strings
  • Exclude results from these domains. Cannot be used with include_domains.
• limit
  • Type: integer
  • Max results per source type.
• tbs
  • Type: string
  • Time-based filter (e.g. "qdr:d" for past day).
• location
  • Type: string
  • Location for localized results.
• country
  • Type: string
  • ISO 3166-1 alpha-2 country code (e.g. "US").
• ignore_invalid_urls
  • Type: boolean
  • Drop URLs that cannot be scraped by other endpoints.
• timeout
  • Type: integer
  • Request timeout in milliseconds.
• highlights
  • Type: boolean
  • Generate query-relevant highlights. Default: true.
• enterprise
  • Type: list of strings
  • Enterprise ZDR options. Values: "zdr", "anon".
• scrape_options
  • Type: keyword list
  • Scrape each search result. See Scrape parameters.

​

Scrape

​

Why use it

​

Preferred SDK method

​

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

• url
  • Type: string (required)
  • The URL to scrape.
• formats
  • Type: list of format strings or maps
  • Output formats. String values: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "changeTracking", "json", "branding", "audio", "video".
  • Map forms: %{type: "json", prompt: ..., schema: ...}, %{type: "screenshot", fullPage: true}, %{type: "changeTracking", modes: ["git-diff"]}.
• headers
  • Type: map
  • Custom HTTP headers.
• include_tags
  • Type: list of strings
  • Include only specific HTML tags.
• exclude_tags
  • Type: list of strings
  • Exclude specific HTML tags.
• only_main_content
  • Type: boolean
  • Strip nav, footer, and boilerplate.
• timeout
  • Type: integer
  • Timeout in milliseconds. Default: 60000, max: 300000.
• wait_for
  • Type: integer
  • Wait time in ms before fetching content.
• mobile
  • Type: boolean
  • Emulate mobile viewport.
• parsers
  • Type: list of strings or maps
  • File parsing controls. "pdf" or %{type: "pdf", mode: "fast" | "auto" | "ocr", maxPages: integer}.
• actions
  • Type: list of maps
  • Browser actions. Types: wait, screenshot, click (selector, all?), write (text), press (key), scroll (direction), scrape, executeJavascript (script), pdf.
• location
  • Type: keyword list
  • Geo or language-aware scraping. Keys: country:, languages:.
• skip_tls_verification
  • Type: boolean
  • Skip TLS certificate verification.
• remove_base64_images
  • Type: boolean
  • Drop base64 images from markdown output.
• block_ads
  • Type: boolean
  • Ad and cookie popup blocking.
• proxy
  • Type: atom or string
  • Proxy control. Values: :basic, :enhanced, :auto.
• max_age
  • Type: integer
  • Use cached data if younger than this (ms).
• min_age
  • Type: integer
  • Only check cache, never trigger fresh scrape (ms).
• store_in_cache
  • Type: boolean
  • Cache the result.
• lockdown
  • Type: boolean
  • Serve from cache only, never make outbound requests.
• redact_pii
  • Type: boolean
  • Redact personally identifiable information.
• profile
  • Type: keyword list
  • Persistent browser profile. Keys: name:, save_changes:.
• audit_metadata
  • Type: keyword list
  • User attribution for SIEM logging. Required key: username:.
• zero_data_retention
  • Type: boolean
  • Enable zero data retention for this scrape.

​

Interact

​

Why use it

​

Preferred SDK method

​

Example

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

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

​

Parameters

• job_id
  • Type: string (required, first positional argument)
  • Scrape job ID.
• code
  • Type: string (required)
  • Code to execute in the browser session.
• language
  • Type: atom or string
  • Execution runtime. Values: :python, :node, :bash.
• timeout
  • Type: integer
  • Execution timeout in seconds.
• origin
  • Type: string
  • Optional origin label for execution telemetry.

​

Stop session

​

Notes

• This SDK exposes code-based interactions only (no prompt parameter on interact_with_scrape_browser_session).
• Every function has a bang (!) variant that raises on error instead of returning {:error, _}.
• There is no client struct; the Req HTTP client is rebuilt per-call from opts.
• All params are snake_case keywords, mapped to camelCase JSON at serialization time.
• Parameters are validated at call time with NimbleOptions before any HTTP request.
• Origin telemetry ("elixir-sdk@{version}") is injected into every POST body automatically.

​

Source Of Truth

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