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

Install

Add to mix.exs:

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

Then run:

mix deps.get

Authenticate

Set the API key globally in your config:

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

Or pass it per-request:

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

All functions accept an optional trailing keyword list (opts) that supports :api_key and :base_url (for self-hosted instances, default "https://api.firecrawl.dev/v2").

When To Use What

• search_and_scrape: Use when you start with a query and need to discover relevant URLs and their content.
• scrape_and_extract_from_url: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats.
• interact_with_scrape_browser_session: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session.

Search

Why use it

Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction.

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,
  highlights: true
)

IO.inspect(response.body)

Parameters

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

Parameter	Elixir Key	JSON Key	Type	Description
query	:query	"query"	:string	The search query (required).
limit	:limit	"limit"	:integer	Maximum number of results. Server default: 10.
sources	:sources	"sources"	{:list, :any}	Sources to search: "web", "news", "images".
categories	:categories	"categories"	{:list, :any}	Filter by category: "github", "research", "pdf", "developer".
include_domains	:include_domains	"includeDomains"	{:list, :string}	Restrict results to these domains.
exclude_domains	:exclude_domains	"excludeDomains"	{:list, :string}	Exclude results from these domains.
tbs	:tbs	"tbs"	:string	Time-based filter (e.g. "qdr:d" for past day).
location	:location	"location"	:string	Location for geo-targeted search.
country	:country	"country"	:string	ISO country code (e.g. "US").
ignore_invalid_urls	:ignore_invalid_urls	"ignoreInvalidURLs"	:boolean	Ignore invalid URLs in results.
timeout	:timeout	"timeout"	:integer	Timeout in milliseconds. Server default: 60000.
highlights	:highlights	"highlights"	:boolean	Generate query-relevant highlights. Server default: true.
scrape_options	:scrape_options	"scrapeOptions"	:keyword_list	Nested scrape configuration.
enterprise	:enterprise	"enterprise"	{:list, :string}	Enterprise ZDR options: ["zdr"] or ["anon"].

Scrape

Why use it

Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more.

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["data"]["markdown"])

Parameters

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

Parameter	Elixir Key	JSON Key	Type	Description
url	:url	"url"	:string	The URL to scrape (required).
formats	:formats	"formats"	{:list, :any}	Output formats: "markdown", "html", "rawHtml", "links", "images", "screenshot", "json", etc. Server default: ["markdown"].
only_main_content	:only_main_content	"onlyMainContent"	:boolean	Strip boilerplate. Server default: true.
headers	:headers	"headers"	:any	Custom HTTP headers.
include_tags	:include_tags	"includeTags"	{:list, :string}	HTML tags to include.
exclude_tags	:exclude_tags	"excludeTags"	{:list, :string}	HTML tags to exclude.
timeout	:timeout	"timeout"	:integer	Timeout in ms. Min: 1000, max: 300000. Server default: 60000.
wait_for	:wait_for	"waitFor"	:integer	Delay in ms before fetching content.
mobile	:mobile	"mobile"	:boolean	Emulate mobile device.
parsers	:parsers	"parsers"	{:list, :any}	Parser configurations. Server default: ["pdf"].
actions	:actions	"actions"	{:list, :any}	Browser automation actions.
location	:location	"location"	:keyword_list	Location settings.
skip_tls_verification	:skip_tls_verification	"skipTlsVerification"	:boolean	Skip TLS verification.
remove_base64_images	:remove_base64_images	"removeBase64Images"	:boolean	Remove base64 images. Server default: true.
block_ads	:block_ads	"blockAds"	:boolean	Block advertisements. Server default: true.
proxy	:proxy	"proxy"	:basic | :enhanced | :auto	Proxy type. Server default: :auto.
max_age	:max_age	"maxAge"	:integer	Use cached result if younger than this (ms).
min_age	:min_age	"minAge"	:integer	Cache-only mode. Set to 1 for any cached data.
store_in_cache	:store_in_cache	"storeInCache"	:boolean	Cache the result. Server default: true.
lockdown	:lockdown	"lockdown"	:boolean	Only serve cached results.
redact_pii	:redact_pii	"redactPII"	:boolean	Redact PII from content.
profile	:profile	"profile"	:keyword_list	Browser profile for session continuity.
audit_metadata	:audit_metadata	"auditMetadata"	:keyword_list	User attribution: [username: "..."].
zero_data_retention	:zero_data_retention	"zeroDataRetention"	:boolean	Enable zero data retention.

Interact

Why use it

Execute code in a live browser session tied to a scrape job. Use 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, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
  code: "document.title",
  language: :node
)

IO.inspect(result.body)

Firecrawl.stop_interactive_scrape_browser_session(job_id)

Parameters

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

Parameter	Elixir Key	JSON Key	Type	Description
job_id	first argument	URL path	String.t()	The scrape job ID (required).
code	:code	"code"	:string	Code to execute in the browser sandbox (required).
language	:language	"language"	:python | :node | :bash	Execution language. Server default: :node.
timeout	:timeout	"timeout"	:integer	Execution timeout in seconds. Range: 1-300. Server default: 30.
origin	:origin	"origin"	:string	Origin label for telemetry.

Use Firecrawl.stop_interactive_scrape_browser_session(job_id) to end the browser session.

Notes

• Naming style: Parameters use snake_case atom keys. The SDK converts them to camelCase JSON keys 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, not scrape).
• Return type: All functions return {:ok, %Req.Response{}} or {:error, exception}. The bang variants (!) raise on error and return Req.Response.t() directly. HTTP 4xx/5xx responses raise Firecrawl.Error with :status and :body fields.
• No prompt support: Unlike JS/Python/Rust, the Elixir SDK interact_with_scrape_browser_session only accepts code, not a natural-language prompt.
• Origin auto-injection: The SDK automatically injects "origin": "elixir-sdk@{version}" into 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