Firecrawl Elixir Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (firecrawl hex package, firecrawl/apps/elixir-sdk) and the v2 OpenAPI spec. Function names and parameters match the auto-generated client.

Install

# mix.exs
defp deps do
  [
    {:firecrawl, "~> 1.9"}
  ]
end

Authenticate

# Option 1: Application config (config/config.exs)
config :firecrawl, api_key: "fc-YOUR_API_KEY"

# Option 2: Per-request option
Firecrawl.search_and_scrape([query: "example"], api_key: "fc-YOUR_API_KEY")

All functions accept api_key and base_url (defaults to https://api.firecrawl.dev/v2) as options in the last keyword list argument. If no API key is provided, requests fall back to a keyless free tier (rate-limited per IP).

When To Use What

search_and_scrape: use when you start with a query and need discovery.
scrape_and_extract_from_url: use when you already have a URL and want page content.
interact_with_scrape_browser_session: use when the page needs clicks, forms, or post-scrape browser actions.

Search

Why use it

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with.

Preferred SDK method

Firecrawl.search_and_scrape(params, opts) → {:ok, Req.Response.t()} | {:error, Exception.t()} Bang variant: Firecrawl.search_and_scrape!(params, opts) raises on error.

Example

{:ok, response} = Firecrawl.search_and_scrape(
  query: "site:docs.firecrawl.dev webhooks",
  limit: 5,
  scrape_options: [formats: ["markdown"]]
)

# response.body contains the parsed JSON response
for item <- response.body["data"]["web"] || [] do
  IO.puts("#{item["url"]} #{item["title"]}")
end

Parameters

Parameters are passed as a keyword list (first argument). All are optional except query.

Parameter	Type	Description	When to use
`query`	`:string` (required)	The search query.	Always required.
`sources`	`{:list, :any}`	Sources to search.	When you want news or image results.
`categories`	`{:list, :any}`	Filter by category.	When filtering by category.
`include_domains`	`{:list, :string}`	Restrict results to these domains.	When targeting specific sites.
`exclude_domains`	`{:list, :string}`	Exclude results from these domains.	When filtering out specific sites.
`limit`	`:integer`	Max results to return.	When you need to cap results.
`tbs`	`:string`	Time-based filter (e.g. `"qdr:d"`).	When you need time-constrained results.
`location`	`:string`	Location for localized results.	When you want geo-targeted results.
`country`	`:string`	ISO country code for geo-targeting.	When you want country-specific results.
`ignore_invalid_urls`	`:boolean`	Ignore invalid URLs.	When piping into scrape/interact.
`timeout`	`:integer`	Timeout in milliseconds.	When the default is too short.
`highlights`	`:boolean`	Generate query-relevant highlights.	Set `false` for raw descriptions.
`scrape_options`	`:keyword_list`	Scrape options per result (same fields as scrape params).	When you want full page content.
`enterprise`	`{:list, :string}`	Enterprise options (`"anon"`, `"zdr"`).	Enterprise ZDR use cases.

Scrape

Why use it

Use scrape when you already have a URL and want structured content in one or more formats.

Preferred SDK method

Firecrawl.scrape_and_extract_from_url(params, opts) → {:ok, Req.Response.t()} | {:error, Exception.t()} 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/pricing",
  formats: ["markdown"],
  only_main_content: true
)

IO.puts(response.body["data"]["markdown"])

Parameters

Parameters are passed as a keyword list (first argument). All are optional except url.

Parameter	Type	Description	When to use
`url`	`:string` (required)	The URL to scrape.	Always required.
`formats`	`{:list, :any}`	Output formats (e.g. `["markdown", "html"]`).	Always — controls what data you get back.
`headers`	`:any`	Custom HTTP headers as a map.	When you need cookies, user-agent, etc.
`include_tags`	`{:list, :string}`	HTML tags to include.	When you only want specific tags.
`exclude_tags`	`{:list, :string}`	HTML tags to exclude.	When filtering out specific tags.
`only_main_content`	`:boolean`	Strip nav, footer, boilerplate.	When you want clean content only.
`timeout`	`:integer`	Timeout in milliseconds.	When the default is too short.
`wait_for`	`:integer`	Wait time in ms after page load.	When the page needs JS rendering time.
`mobile`	`:boolean`	Emulate mobile device.	For mobile-specific content.
`parsers`	`{:list, :any}`	Parser configs (e.g. PDF).	When scraping PDF files.
`actions`	`{:list, :any}`	Pre-scrape browser actions.	When you need to interact before scraping.
`location`	`:keyword_list`	Geolocation settings.	For geo-targeted content.
`skip_tls_verification`	`:boolean`	Skip TLS verification.	For sites with invalid certs.
`remove_base64_images`	`:boolean`	Remove base64 images.	For smaller output.
`block_ads`	`:boolean`	Block ads.	When ads interfere with extraction.
`proxy`	`{:in, [:basic, :enhanced, :auto]}`	Proxy type.	For anti-bot protection.
`max_age`	`:integer`	Max cache age.	When cached data is acceptable.
`min_age`	`:integer`	Min cache age.	When you only want cached data.
`store_in_cache`	`:boolean`	Cache the result.	Set `false` for data protection.
`lockdown`	`:boolean`	Serve from cache only.	For ZDR-like behavior.
`redact_pii`	`:boolean`	Redact PII from output.	When output may contain personal info.
`zero_data_retention`	`:boolean`	Enable zero data retention.	For ZDR compliance.
`profile`	`:keyword_list`	Persistent browser profile.	When you need state to persist.
`audit_metadata`	`:keyword_list`	SIEM metadata (keys: `username`).	Enterprise audit logging.

Interact

Why use it

Use interact_with_scrape_browser_session for code execution in the browser session tied to a scrape job. For multi-step interactive flows, prefer this over scrape-time actions.

Preferred SDK method

Firecrawl.interact_with_scrape_browser_session(job_id, params, opts) → {:ok, Req.Response.t()} | {:error, Exception.t()} 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",
  formats: ["markdown"]
)

job_id = scrape_response.body["data"]["metadata"]["scrapeId"]

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

IO.puts(result.body["stdout"])

# Stop the session when done
Firecrawl.stop_interactive_scrape_browser_session(job_id)

Parameters

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

Parameter	Type	Description	When to use
`job_id`	`String.t()` (required, 1st arg)	The scrape job ID.	Always required.
`code`	`:string` (required)	Code to execute in the browser session.	Always required.
`language`	`{:in, [:python, :node, :bash]}`	Runtime language. Default: `:node`.	When your code is in Python or Bash.
`timeout`	`:integer`	Execution timeout in seconds.	When execution may take longer.

Return value

The response body contains: success, cdpUrl, liveViewUrl, interactiveLiveViewUrl, output, stdout, result, stderr, exitCode, killed, error.

Stop session

Firecrawl.stop_interactive_scrape_browser_session(job_id, opts) — ends the browser session.

Notes

The Elixir SDK is auto-generated from the OpenAPI spec. Function names follow the OpenAPI operation IDs rather than simplified aliases.
Function name mapping to other SDKs:
- search_and_scrape = search in other SDKs
- scrape_and_extract_from_url = scrape in other SDKs
- interact_with_scrape_browser_session = interact in other SDKs
- stop_interactive_scrape_browser_session = stopInteraction / stop_interaction in other SDKs
All functions have bang (!) variants that raise instead of returning error tuples.
Parameters use snake_case keys in the keyword list but are serialized to camelCase JSON keys.
The proxy parameter is typed as an enum (:basic, :enhanced, :auto) — note that :stealth is not in the Elixir SDK’s validated values.
Additional Req options (custom headers, adapter config, etc.) can be passed through in the opts keyword list.

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 method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Return value

Stop session

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

​Return value

​Stop session

​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

Return value

Stop session

Notes

Source Of Truth