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 via the Elixir SDK. It is generated from SDK source and the OpenAPI spec.

Install

Add to your mix.exs:

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

Authenticate

The Elixir SDK is a flat module of stateless functions — there is no client struct to construct. Configure the API key globally or pass it per request.

Global config (in config.exs):

config :firecrawl, api_key: "fc-YOUR_API_KEY"

Per-request override:

Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR_API_KEY")

All functions accept trailing opts for :api_key and :base_url (defaults to https://api.firecrawl.dev/v2).

When To Use What

• search_and_scrape — Use when you start with a query and need to discover relevant pages. Returns structured results grouped by source type. Optionally scrapes each result.
• scrape_and_extract_from_url — Use when you already have a URL and want page content in one or more formats (markdown, HTML, JSON extraction, etc.).
• interact_with_scrape_browser_session — Use when the page needs post-scrape browser actions: running code in a live browser session tied to a previous scrape job.

Search

Why use it

Search the web for a query and optionally scrape each result. Returns results grouped by source type. Use this as the starting point when you do not yet have a specific URL.

Preferred SDK method

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

Bang variant: Firecrawl.search_and_scrape!(params, opts) raises on error.

Example

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

IO.inspect(response.body)

Parameters

Parameters are passed as a keyword list. All are optional except query.

Parameter	Type	Description
query	:string	Required. The search query.
limit	:integer	Max number of results.
sources	{:list, :any}	Sources to search. Default: ["web"].
categories	{:list, :any}	Categories to filter results. Default: [].
include_domains	{:list, :string}	Restrict results to 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	Location for search results.
country	:string	ISO country code for geo-targeting (e.g. "US").
timeout	:integer	Timeout in milliseconds.
highlights	:boolean	Generate query-relevant highlights. Default: true.
ignore_invalid_urls	:boolean	Exclude URLs invalid for other Firecrawl endpoints.
scrape_options	:keyword_list	Options for scraping search results.
enterprise	{:list, :string}	Enterprise ZDR options: ["zdr"] or ["anon"].

Return shape

{:ok, %Req.Response{}} — the response body contains results grouped by source type.

Scrape

Why use it

Scrape a single URL and get its content in one or more formats. Use this when you have the exact URL you want content from.

Preferred SDK method

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

Bang variant: Firecrawl.scrape_and_extract_from_url!(params, opts) raises on error.

Example

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

IO.inspect(response.body)

Parameters

Parameters are passed as a keyword list. All are optional except url.

Parameter	Type	Description
url	:string	Required. The URL to scrape.
formats	{:list, :any}	Output formats (e.g. "markdown", "html", "json", "screenshot"). Default: ["markdown"].
only_main_content	:boolean	Only return main content. Default: true.
include_tags	{:list, :string}	HTML tags to include.
exclude_tags	{:list, :string}	HTML tags to exclude.
headers	:any	Custom HTTP headers.
timeout	:integer	Timeout in ms. Default: 60000. Min 1000, max 300000.
wait_for	:integer	Delay in ms before fetching content.
mobile	:boolean	Emulate a mobile device.
parsers	{:list, :any}	File parser config. Default: ["pdf"].
actions	{:list, :any}	Browser actions to perform before grabbing content.
location	:keyword_list	Location settings (proxy, language, timezone).
skip_tls_verification	:boolean	Skip TLS certificate verification.
remove_base64_images	:boolean	Remove base64 images from markdown. Default: true.
block_ads	:boolean	Block ads and cookie popups. Default: true.
proxy	{:in, [:basic, :enhanced, :auto]}	Proxy type. Default: "auto".
max_age	:integer	Max cache age in ms. Default: 172800000 (2 days).
min_age	:integer	Cache-only mode. Min age in ms. Set to 1 for any cache.
store_in_cache	:boolean	Store result in cache. Default: true.
lockdown	:boolean	Only serve cached results.
redact_pii	:boolean	Redact PII from content.
zero_data_retention	:boolean	Enable zero data retention.
profile	:keyword_list	Persistent browser profile.
audit_metadata	:keyword_list	SIEM logging attribution (username required).

Interact

Why use it

Execute code in a live browser session tied to a previous scrape job. Use this for post-scrape interactions like clicking buttons, filling forms, or running scripts.

Preferred SDK method

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

Bang variant: Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts) raises on error.

Example

{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(url: "https://example.com")
job_id = scrape_response.body["data"]["metadata"]["jobId"]

{:ok, response} = Firecrawl.interact_with_scrape_browser_session(job_id,
  code: "document.querySelector('button#submit').click();",
  language: :node,
  timeout: 30
)

IO.inspect(response.body)

Parameters

The first argument is the job_id (path parameter). Remaining parameters are passed as a keyword list.

Parameter	Type	Description
job_id	String.t()	Required (first argument). The scrape job ID.
code	:string	Required. Code to execute in the browser session.
language	{:in, [:python, :node, :bash]}	Execution language. Use :node for JavaScript or :bash for agent-browser CLI commands.
timeout	:integer	Execution timeout in seconds.
origin	:string	Origin label for telemetry.

Related methods

• Firecrawl.stop_interactive_scrape_browser_session(job_id, opts) — Stop the browser session (DELETE /scrape/{jobId}/interact).

Notes

• The SDK is auto-generated from the OpenAPI spec. Function names map 1:1 to OpenAPI operations.
• Parameter names use snake_case in Elixir. They are converted to camelCase for the JSON wire format automatically.
• All functions return {:ok, %Req.Response{}} | {:error, Exception.t() | Firecrawl.Error.t()}.
• Bang variants (e.g. search_and_scrape!) raise on error instead of returning an error tuple.
• There is no client struct — the module is a flat namespace of stateless functions.
• HTTP errors (4xx/5xx) are wrapped in Firecrawl.Error with :status and :body fields.
• Batch scraping is available via Firecrawl.scrape_and_extract_from_urls/2 (POST /batch/scrape).

Source Of Truth

• SDK: firecrawl/apps/elixir-sdk/lib/firecrawl.ex
• OpenAPI: firecrawl-docs/api-reference/v2-openapi.json