Firecrawl Elixir Agent Quickstart

This file is the canonical quickstart for external agents integrating with Firecrawl using the Elixir SDK. It is generated from SDK source and the OpenAPI spec.

Install

Add to your mix.exs dependencies:

{:firecrawl, "~> 1.10"}

Then run:

mix deps.get

Authenticate

Pass the API key as a runtime option on each call:

opts = [api_key: "fc-YOUR_API_KEY"]

To use a self-hosted instance:

opts = [api_key: "fc-YOUR_API_KEY", base_url: "https://your-instance.com"]

When To Use What

search_and_scrape: Use when you start with a query and need to discover relevant pages across the web.
scrape_and_extract_from_url: Use when you already have a URL and want its content (markdown, HTML, structured data, screenshots, etc.).
interact_with_scrape_browser_session: Use when a page needs post-scrape browser actions — clicking, filling forms, executing code in a live browser session.

Search

Why use it

Search the web for a query and optionally scrape each result in one call. Returns results grouped by source type (web, news, images).

Preferred SDK function

Firecrawl.search_and_scrape(params, opts)
Firecrawl.search_and_scrape!(params, opts)

The bang variant (!) raises on error instead of returning {:error, ...}.

Example

{:ok, response} = Firecrawl.search_and_scrape(
  [
    query: "firecrawl web scraping API",
    limit: 5,
    scrape_options: [formats: ["markdown"]]
  ],
  api_key: "fc-YOUR_API_KEY"
)

IO.inspect(response.body)

Parameters

Parameters are a keyword list (first argument).

Parameter	Type	Required	Description
`query`	`:string`	Yes	The search query string.
`sources`	`{:list, :any}`	No	Sources to search: `"web"`, `"news"`, `"images"`. Default: `["web"]`.
`categories`	`{:list, :any}`	No	Filter results: `"github"`, `"research"`, `"pdf"`, `"developer"`.
`include_domains`	`{:list, :string}`	No	Restrict results to these domains.
`exclude_domains`	`{:list, :string}`	No	Exclude results from these domains.
`limit`	`:integer`	No	Max results per source type. Default: `10`. Max: `100`.
`tbs`	`:string`	No	Time-based search filter (e.g. `"qdr:d"` for past day).
`location`	`:string`	No	Geographic location string.
`country`	`:string`	No	ISO country code for geo-targeting.
`ignore_invalid_urls`	`:boolean`	No	Exclude invalid URLs from results. Default: `false`.
`timeout`	`:integer`	No	Timeout in milliseconds. Default: `60000`.
`highlights`	`:boolean`	No	Generate query-relevant highlights. Default: `true`.
`scrape_options`	`:keyword_list`	No	Options applied when scraping each result.
`enterprise`	`{:list, :string}`	No	Enterprise ZDR options.

Return type

{:ok, %Req.Response{}} or {:error, exception}. The response body contains "data" with "web", "news", "images" arrays.

Scrape

Why use it

Scrape a single URL and get back clean markdown, HTML, structured JSON, screenshots, or other formats. Supports browser actions, location targeting, and caching.

Preferred SDK function

Firecrawl.scrape_and_extract_from_url(params, opts)
Firecrawl.scrape_and_extract_from_url!(params, opts)

Example

{:ok, response} = Firecrawl.scrape_and_extract_from_url(
  [
    url: "https://example.com",
    formats: ["markdown", "links"]
  ],
  api_key: "fc-YOUR_API_KEY"
)

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

Parameters

Parameters are a keyword list (first argument).

Parameter	Type	Required	Description
`url`	`:string`	Yes	The URL to scrape.
`formats`	`{:list, :any}`	No	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or maps with format-specific options. Default: `["markdown"]`.
`only_main_content`	`:boolean`	No	Extract main content only. Default: `true`.
`include_tags`	`{:list, :string}`	No	HTML tags to include.
`exclude_tags`	`{:list, :string}`	No	HTML tags to exclude.
`headers`	`:any`	No	Custom HTTP headers.
`timeout`	`:integer`	No	Timeout in milliseconds. Default: `60000`.
`wait_for`	`:integer`	No	Extra delay in ms before fetching content. Default: `0`.
`mobile`	`:boolean`	No	Emulate a mobile device. Default: `false`.
`actions`	`{:list, :any}`	No	Browser actions: wait, click, write, press, scroll, screenshot, scrape, executeJavascript, pdf.
`location`	`:keyword_list`	No	Location targeting with `country` and `languages`.
`skip_tls_verification`	`:boolean`	No	Skip TLS verification. Default: `true`.
`remove_base64_images`	`:boolean`	No	Remove base64 images from markdown. Default: `true`.
`block_ads`	`:boolean`	No	Block ads and cookie popups. Default: `true`.
`proxy`	`:basic \| :enhanced \| :auto`	No	Proxy type. Default: `"auto"`.
`max_age`	`:integer`	No	Cache max age in milliseconds. Default: `172800000` (2 days).
`min_age`	`:integer`	No	Cache-only: minimum cache age in ms.
`store_in_cache`	`:boolean`	No	Store result in cache. Default: `true`.
`lockdown`	`:boolean`	No	Cache-only mode. Default: `false`.
`parsers`	`{:list, :any}`	No	File parser configs. Default: `["pdf"]`.
`redact_pii`	`:boolean`	No	Redact PII from markdown. Default: `false`.
`profile`	`:keyword_list`	No	Persistent browser profile.
`audit_metadata`	`:keyword_list`	No	User attribution for SIEM logging (requires `username`).
`zero_data_retention`	`:boolean`	No	Enable zero data retention for this scrape.

Return type

{:ok, %Req.Response{}} or {:error, exception}. The response body "data" contains the scraped document fields.

Interact

Why use it

Run code in the live browser session of an existing scrape job. Use it for clicks, form fills, navigation, or any post-scrape browser automation.

Preferred SDK function

Firecrawl.interact_with_scrape_browser_session(job_id, params, opts)
Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts)

Example

# First, scrape a page to get a job ID
{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(
  [url: "https://example.com"],
  api_key: "fc-YOUR_API_KEY"
)

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

# Then interact with the browser session
{:ok, response} = Firecrawl.interact_with_scrape_browser_session(
  job_id,
  [
    code: ~s|document.querySelector("button.submit").click();|,
    language: :node
  ],
  api_key: "fc-YOUR_API_KEY"
)

IO.inspect(response.body)

Parameters

Parameter	Type	Required	Description
`job_id`	`String.t()`	Yes	The scrape job ID (path parameter).
`code`	`:string`	Yes	Code to execute in the browser sandbox.
`language`	`:python \| :node \| :bash`	No	Runtime language. Default: `"node"`.
`timeout`	`:integer`	No	Execution timeout in seconds. Default: `30`. Min: `1`, Max: `300`.
`origin`	`:string`	No	Origin label for execution telemetry.

Return type

{:ok, %Req.Response{}} or {:error, exception}. The response body contains .success, .stdout, .result, .stderr, .exitCode, .error.

Stopping a session

Firecrawl.stop_interactive_scrape_browser_session(job_id, api_key: "fc-YOUR_API_KEY")

Notes

Naming style: All parameters use snake_case atoms in keyword lists. The SDK serializes to camelCase for the API.
OpenAPI-generated: The Elixir SDK is generated from the OpenAPI spec. Function names reflect the API operation IDs rather than shortened aliases.
Function naming:
- Search: search_and_scrape (not search)
- Scrape: scrape_and_extract_from_url (not scrape)
- Interact: interact_with_scrape_browser_session (not interact)
- Stop interaction: stop_interactive_scrape_browser_session
Bang variants: Every function has a ! variant that raises Firecrawl.Error on non-2xx responses instead of returning {:error, ...}.
Req-based: The SDK uses the Req HTTP library. Runtime options (second or third argument) accept :api_key, :base_url, and any Req option.
No deprecated aliases: The Elixir SDK has no deprecated function names.

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

Return type

Scrape

Why use it

Preferred SDK function

Example

Parameters

Return type

Interact

Why use it

Preferred SDK function

Example

Parameters

Return type

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

​Return type

​Scrape

​Why use it

​Preferred SDK function

​Example

​Parameters

​Return type

​Interact

​Why use it

​Preferred SDK function

​Example

​Parameters

​Return type

​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

Return type

Scrape

Why use it

Preferred SDK function

Example

Parameters

Return type

Interact

Why use it

Preferred SDK function

Example

Parameters

Return type

Stopping a session

Notes

Source Of Truth