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

Getting Started

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Cookbooks

Elixir Agent Quickstart

Firecrawl Elixir Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK function

Example

Parameters

Scrape

Why use it

Preferred SDK function

Example

Parameters

Interact

Why use it

Preferred SDK function

Example

Parameters

Stopping a session

Notes

Source Of Truth

​Firecrawl Elixir Agent Quickstart

​Install

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK function

​Example

​Parameters

​Scrape

​Why use it

​Preferred SDK function

​Example

​Parameters

​Interact

​Why use it

​Preferred SDK function

​Example

​Parameters

​Stopping a session

​Notes

​Source Of Truth

Firecrawl Elixir Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK function

Example

Parameters

Scrape

Why use it

Preferred SDK function

Example

Parameters

Interact

Why use it

Preferred SDK function

Example

Parameters

Stopping a session

Notes

Source Of Truth