Firecrawl Elixir Agent Quickstart

Canonical quickstart for external agents. Generated from the firecrawl Elixir SDK source and the v2 OpenAPI spec. Function names match the auto-generated module in lib/firecrawl.ex.

Install

Add to mix.exs:

{:firecrawl, "~> 1.11"}

Authenticate

# config/runtime.exs or config.exs
config :firecrawl, api_key: System.get_env("FIRECRAWL_API_KEY")

# Or pass api_key per call:
{:ok, res} = Firecrawl.search_and_scrape(
  [query: "firecrawl webhooks"],
  api_key: "fc-your-api-key"
)

Every function accepts base_url in opts (defaults to "https://api.firecrawl.dev/v2"). Additional opts are passed through to Req.

When To Use What

search: use when you start with a query and need discovery. Returns relevant pages you can then scrape or interact with.
scrape: use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
interact: use when the page needs clicks, form fills, or other browser actions after a scrape has created a session. Requires a scrape job ID from a prior scrape.

Search

Why use it

Discover relevant pages from a query. Constrain results to a site with site: in the query string (e.g. site:docs.firecrawl.dev webhooks).

Preferred SDK method

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

Example

{:ok, res} = Firecrawl.search_and_scrape(query: "site:docs.firecrawl.dev webhook retries")

Every function has a bang variant (search_and_scrape!) that raises on error.

Parameters

Keyword list params:

Parameter	Type	Required	Description
`query`	`string`	yes	Search query. Use `site:example.com` to scope to a domain.
`sources`	`list`	no	Which sources to search: `:web`, `:news`, `:images` (atoms or strings).
`categories`	`list`	no	Filter by category: `:developer`, `:research`, `:pdf` (atoms or strings).
`include_domains`	`list(string)`	no	Restrict results to these domains.
`exclude_domains`	`list(string)`	no	Exclude results from these domains.
`limit`	`integer`	no	Maximum number of results.
`tbs`	`string`	no	Time-based filter (e.g. `"qdr:d"` for past day).
`location`	`string`	no	Localized results.
`country`	`string`	no	ISO 3166-1 alpha-2 country code (e.g. `"US"`).
`ignore_invalid_urls`	`boolean`	no	Drop URLs that cannot be scraped.
`timeout`	`integer`	no	Request timeout in milliseconds.
`highlights`	`boolean`	no	Generate query-relevant highlights.
`scrape_options`	`keyword list`	no	Scrape each search result. See Scrape parameters.
`enterprise`	`list(string)`	no	Enterprise controls: `"zdr"` (zero data retention), `"anon"` (anonymized).

Scrape

Why use it

Retrieve structured content from a URL in one or more formats: markdown, HTML, JSON extraction, screenshots, and more.

Preferred SDK method

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

Example

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

Parameters

Keyword list params:

Parameter	Type	Required	Description
`url`	`string`	yes	The URL to scrape.
`formats`	`list`	no	Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`. Maps: `%{type: "json", prompt: ..., schema: ...}`, `%{type: "screenshot", fullPage: true}`, `%{type: "changeTracking", modes: ["git-diff"]}`, `%{type: "attributes", selectors: [...]}`.
`headers`	`map`	no	Custom HTTP headers sent with the request.
`include_tags`	`list(string)`	no	Only include content from these HTML tags.
`exclude_tags`	`list(string)`	no	Exclude content from these HTML tags.
`only_main_content`	`boolean`	no	Strip nav, footer, and other boilerplate.
`timeout`	`integer`	no	Request timeout in milliseconds.
`wait_for`	`integer`	no	Wait for the page to render (milliseconds).
`mobile`	`boolean`	no	Emulate a mobile viewport.
`parsers`	`list`	no	File parsing controls: `"pdf"` or `%{type: "pdf", mode: "fast" \| "auto" \| "ocr", maxPages: n}`.
`actions`	`list(map)`	no	Browser actions before scraping: `%{type: "click", selector: ...}`, `%{type: "wait", milliseconds: ...}`, `%{type: "write", text: ...}`, `%{type: "press", key: ...}`, `%{type: "scroll", direction: "up" \| "down"}`, `%{type: "scrape"}`, `%{type: "executeJavascript", script: ...}`, `%{type: "pdf"}`.
`location`	`keyword list`	no	Geo targeting: `[country: "US", languages: ["en-US"]]`.
`skip_tls_verification`	`boolean`	no	Skip TLS certificate verification.
`remove_base64_images`	`boolean`	no	Drop base64 images from markdown output.
`block_ads`	`boolean`	no	Block ads and cookie popups.
`proxy`	`:basic \| :enhanced \| :auto`	no	Proxy mode.
`max_age`	`integer`	no	Use cached content if younger than this (milliseconds).
`min_age`	`integer`	no	Use cached content only if at least this old (milliseconds).
`store_in_cache`	`boolean`	no	Cache the scrape result.
`lockdown`	`boolean`	no	Serve only cached results; no outbound requests.
`redact_pii`	`boolean`	no	Redact personally identifiable information.
`audit_metadata`	`keyword list`	no	User attribution for SIEM logging: `[username: "..."]`.
`profile`	`keyword list`	no	Persistent browser profile: `[name: "...", save_changes: true]`.
`zero_data_retention`	`boolean`	no	End-to-end zero data retention.

Interact

Why use it

Control the browser session tied to a prior scrape. Use for code execution in the browser session. Requires a scrape job ID from a prior scrape response.

Preferred SDK method

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

Example

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

job_id = get_in(scrape_res.body, ["data", "metadata", "scrapeId"])

{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
  code: "console.log(await page.title());",
  language: :node
)

To stop the session: Firecrawl.stop_interactive_scrape_browser_session(job_id)

Parameters

Parameter	Type	Required	Description
`job_id`	`string`	yes	Scrape job ID (path parameter).
`code`	`string`	yes	Code to execute in the browser session.
`language`	`:python \| :node \| :bash`	no	Runtime for code execution.
`timeout`	`integer`	no	Execution timeout in seconds.

Notes

Function names are auto-generated from the OpenAPI spec and follow a verbose pattern: scrape_and_extract_from_url, search_and_scrape, interact_with_scrape_browser_session. Use them exactly as named.
Every function has a bang variant (e.g. search_and_scrape!) that raises Firecrawl.Error on failure instead of returning {:error, ...}.
Parameter names in the keyword list use snake_case (e.g. only_main_content, scrape_options), which the SDK converts to camelCase JSON keys before sending.
The Elixir SDK’s interact_with_scrape_browser_session only exposes the code parameter, not prompt. For natural-language browser instructions, use the HTTP API directly or another SDK.
No deprecated aliases exist — the SDK is auto-generated from the OpenAPI spec.
Proxy values use atoms (:basic, :enhanced, :auto) rather than strings.
All functions accept api_key and base_url in the trailing opts keyword list.

Source Of Truth

firecrawl/apps/elixir-sdk/lib/firecrawl.ex
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 method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth

​Firecrawl Elixir Agent Quickstart

​Install

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK method

​Example

​Parameters

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Interact

​Why use it

​Preferred SDK method

​Example

​Parameters

​Notes

​Source Of Truth

Firecrawl Elixir Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth