Elixir Agent Quickstart

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

Firecrawl Elixir Agent Quickstart

This file is the canonical quickstart for external agents integrating with Firecrawl using the official Elixir SDK. It is generated from SDK source and OpenAPI spec.

Install

Add to your mix.exs:

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

Then run:

mix deps.get

Authenticate

Configure via application config:

# config/config.exs
config :firecrawl, api_key: "fc-YOUR_API_KEY"

Or pass the API key per-request via the opts keyword:

Firecrawl.search_and_scrape([query: "example"], api_key: "fc-YOUR_API_KEY")

For self-hosted instances, set the base URL:

config :firecrawl,
  api_key: "fc-YOUR_API_KEY",
  base_url: "https://your-firecrawl-instance.com/v2"

The default base URL is "https://api.firecrawl.dev/v2". Omitting the API key enables the keyless free tier (rate-limited per IP).

When To Use What

• search_and_scrape — Use when you start with a query and need to discover relevant URLs and their content. Returns categorized results from web, news, and images.
• scrape_and_extract_from_url — Use when you already have a URL and want to extract page content in structured formats (markdown, HTML, JSON, screenshots, etc.).
• interact_with_scrape_browser_session — Use when the page needs post-scrape browser actions: running code in the live browser session.

Search

Why use it

Search finds relevant pages across the web for a given query, optionally scraping the results. It returns results grouped by source type.

Preferred SDK function

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

Example

{:ok, results} = Firecrawl.search_and_scrape(
  query: "firecrawl web scraping API",
  limit: 5,
  highlights: true
)

IO.inspect(results)

The bang variant raises Firecrawl.Error on failure:

results = Firecrawl.search_and_scrape!(
  query: "firecrawl web scraping API",
  limit: 5
)

Parameters

All parameters are passed as a keyword list. Only query is required.

Parameter	Type	Description
query	:string	The search query (required).
limit	:integer	Maximum number of results to return.
sources	{:list, :any}	Source types to search. Defaults to ["web"].
categories	{:list, :any}	Filter results by category.
include_domains	{:list, :string}	Only include results from these domains.
exclude_domains	{:list, :string}	Exclude results from these domains.
tbs	:string	Time-based search filter (e.g. "qdr:d" for past day).
location	:string	Geographic location for search results (e.g. "San Francisco,California,United States").
country	:string	ISO country code for geo-targeting (e.g. "US").
ignore_invalid_urls	:boolean	Exclude invalid URLs from results.
timeout	:integer	Timeout in milliseconds.
highlights	:boolean	Generate query-relevant highlights. Defaults to true.
scrape_options	:keyword_list	Options for scraping search results. Accepts the same parameters as scrape.
enterprise	{:list, :string}	Enterprise ZDR options: ["zdr"] or ["anon"].

Scrape

Why use it

Scrape extracts content from a single URL and returns it in one or more formats: markdown, HTML, raw HTML, JSON (via schema), screenshots, links, images, audio, video, and more.

Preferred SDK function

Firecrawl.scrape_and_extract_from_url(params, opts \\ [])
Firecrawl.scrape_and_extract_from_url!(params, opts \\ [])

Example

{:ok, doc} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com",
  formats: ["markdown", "links"]
)

IO.puts(doc["data"]["markdown"])

Parameters

All parameters are passed as a keyword list. Only url is required.

Parameter	Type	Description
url	:string	The URL to scrape (required).
formats	{:list, :any}	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "summary", "json", "audio", "video", etc.
headers	:any	Custom HTTP headers (cookies, user-agent, etc.).
include_tags	{:list, :string}	Only include content from these HTML tags.
exclude_tags	{:list, :string}	Exclude content from these HTML tags.
only_main_content	:boolean	Only return main content, excluding navbars, footers, etc.
timeout	:integer	Timeout in milliseconds. Default: 60000, Min: 1000, Max: 300000.
wait_for	:integer	Wait time in milliseconds before scraping.
mobile	:boolean	Scrape as a mobile device.
parsers	{:list, :any}	File processing control (e.g. PDF settings).
actions	{:list, :any}	Actions to execute before content extraction.
location	:keyword_list	Geolocation settings. Defaults to US.
skip_tls_verification	:boolean	Skip TLS certificate verification.
remove_base64_images	:boolean	Remove base64-encoded images from markdown output.
block_ads	:boolean	Block advertisements and cookie popups.
proxy	{:in, [:basic, :enhanced, :auto]}	Proxy type.
max_age	:integer	Use cached result if younger than this many milliseconds. Defaults to 2 days.
min_age	:integer	Cache-only mode; minimum age in milliseconds.
store_in_cache	:boolean	Whether to cache the result.
lockdown	:boolean	Only serve previously cached results.
redact_pii	:boolean	Redact personally identifiable information.
audit_metadata	:keyword_list	User attribution for SIEM logging. Keys: username (required).
profile	:keyword_list	Persistent browser storage across sessions.
zero_data_retention	:boolean	Enable zero data retention.

Interact

Why use it

Interact lets you execute code in a live browser session that was opened by a prior scrape call. Use it for clicking buttons, filling forms, navigating multi-step flows, or extracting dynamic content.

Preferred SDK function

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

Example

{:ok, doc} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com",
  formats: ["markdown"]
)

job_id = doc["data"]["metadata"]["jobId"]

{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
  code: "document.querySelector('button.load-more').click()",
  language: :node,
  timeout: 30
)

IO.inspect(result)

Parameters

The job_id is passed as the first positional argument. Remaining parameters are a keyword list.

Parameter	Type	Description
job_id	String.t()	The scrape job ID from a prior scrape call (required, first argument).
code	:string	Code to execute in the browser sandbox (required).
language	{:in, [:python, :node, :bash]}	Language for code execution.
timeout	:integer	Execution timeout in seconds.
origin	:string	Origin label for telemetry.

Stopping a session

{:ok, result} = Firecrawl.stop_interactive_scrape_browser_session(job_id)

Notes

• Naming style: Function names and parameters use snake_case, matching Elixir conventions. The SDK converts to camelCase for the API automatically.
• OpenAPI-generated: The Elixir SDK is auto-generated from the OpenAPI spec. Function names match the OpenAPI operation IDs directly (e.g. scrape_and_extract_from_url rather than just scrape).
• Return values: Regular functions return {:ok, response} or {:error, %Firecrawl.Error{}}. Bang variants (!) return the response directly or raise.
• No deprecated aliases: The Elixir SDK does not have deprecated method aliases.
• Per-request options: The trailing opts keyword list can include api_key: and base_url: to override the application config for a single request.
• Origin: The SDK automatically injects "elixir-sdk@{version}" as the origin in every request body.

Source Of Truth

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