Firecrawl Elixir Agent Quickstart

Canonical quickstart for external agents integrating with Firecrawl using the Elixir SDK. Generated from SDK source and OpenAPI spec.

Install

Add to your mix.exs dependencies:

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

Then run:

mix deps.get

Authenticate

Configure the API key in your application config:

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

Or pass the API key per-call via the opts keyword list:

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

The API key is sent as a Bearer token. A nil or empty key falls back to the keyless free tier (rate-limited per IP). You can also override the base URL per-call:

Firecrawl.scrape_and_extract_from_url([url: "https://example.com"],
  base_url: "https://your-instance.example.com/v2"
)

When To Use What

search_and_scrape: You start with a query and need to discover relevant URLs and their content. Use when you don’t have a specific URL yet.
scrape_and_extract_from_url: You already have a URL and want its page content as markdown, HTML, or structured JSON. Use for targeted extraction.
interact_with_scrape_browser_session: The page needs clicks, form fills, or other browser actions after an initial scrape. Use for multi-step browser automation.

Search

Why use it

Search the web for a query and optionally scrape the results. Returns structured results grouped by source type (web, news, images). Use this when you need to discover relevant pages before extracting content.

Preferred SDK method

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

Bang variant search_and_scrape!/2 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"]]
)

# response is a %Req.Response{} with JSON body
for result <- response.body["data"]["web"] || [] do
  IO.puts("#{result["title"]} #{result["url"]}")
  IO.puts(result["markdown"])
end

Parameters

All parameters are passed as a keyword list. Required parameters are marked.

Parameter	Type	Description
`query`	`:string`	Required. The search query string.
`sources`	`list(any)`	Sources to search: `"web"`, `"news"`, `"images"`. Default: `["web"]`.
`categories`	`list(any)`	Narrow results by category.
`include_domains`	`list(string)`	Restrict results to these domains.
`exclude_domains`	`list(string)`	Exclude results from these domains.
`limit`	`:integer`	Max results per source type.
`tbs`	`:string`	Time-based filter. `"qdr:d"` (day), `"qdr:w"` (week), etc.
`location`	`:string`	Geographic location for results.
`country`	`:string`	ISO country code for geo-targeting.
`timeout`	`:integer`	Timeout in milliseconds.
`highlights`	`:boolean`	Generate query-relevant highlights. Default: `true`.
`ignore_invalid_urls`	`:boolean`	Exclude invalid URLs.
`scrape_options`	`:keyword_list`	Scrape options applied to each result.
`enterprise`	`list(string)`	Enterprise options: `["zdr"]`, `["anon"]`.

Scrape

Why use it

Scrape a single URL and get its content as markdown, HTML, screenshots, structured JSON, or other formats. The primary tool for extracting page content when you already know the URL.

Preferred SDK method

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

Bang variant scrape_and_extract_from_url!/2 raises on error.

Example

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

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

Parameters

Parameter	Type	Description
`url`	`:string`	Required. The URL to scrape.
`formats`	`list(any)`	Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Default: `["markdown"]`.
`only_main_content`	`:boolean`	Only return main content. Default: `true`.
`include_tags`	`list(string)`	HTML tags to include.
`exclude_tags`	`list(string)`	HTML tags to exclude.
`headers`	`:any`	Custom HTTP headers.
`timeout`	`:integer`	Timeout in milliseconds. Default: `60000`. Range: 1000-300000.
`wait_for`	`:integer`	Delay in ms before fetching.
`mobile`	`:boolean`	Emulate a mobile device.
`parsers`	`list(any)`	Parser config (e.g. PDF).
`actions`	`list(any)`	Browser actions before grabbing content.
`location`	`:keyword_list`	Location settings. Default country: `"US"`.
`skip_tls_verification`	`:boolean`	Skip TLS verification.
`remove_base64_images`	`:boolean`	Remove base64 images from markdown.
`block_ads`	`:boolean`	Block ads and cookie popups.
`proxy`	`:basic \| :enhanced \| :auto`	Proxy type. Pass as atoms.
`max_age`	`:integer`	Use cached result if younger (ms). Default: 2 days.
`min_age`	`:integer`	Cache-only mode with minimum age (ms).
`store_in_cache`	`:boolean`	Store result in cache.
`lockdown`	`:boolean`	Serve only cached results.
`redact_pii`	`:boolean`	Redact PII.
`profile`	`:keyword_list`	Browser profile: `[name: "my-profile"]`.
`audit_metadata`	`:keyword_list`	SIEM attribution: `[username: "user@example.com"]`.
`zero_data_retention`	`:boolean`	Enable zero data retention.

Interact

Why use it

Execute code in the browser session created by a prior scrape. Use this for multi-step workflows: scrape a page first to get a job ID, then interact with the live browser to click buttons, fill forms, or run JavaScript.

Preferred SDK method

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

Bang variant interact_with_scrape_browser_session!/3 raises on error.

Example

# First scrape to get a session
{:ok, scrape_response} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com",
  formats: ["markdown"]
)
job_id = scrape_response.body["data"]["metadata"]["jobId"]

# Execute code in the browser
{:ok, result} = Firecrawl.interact_with_scrape_browser_session(job_id,
  code: "document.querySelector('button.load-more').click();",
  language: :node,
  timeout: 30
)

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

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

Parameters

Parameter	Type	Description
`job_id`	`String.t()`	Required. First positional argument. The scrape job ID from a prior scrape.
`code`	`:string`	Required. Code to execute in the browser sandbox.
`language`	`:python \| :node \| :bash`	Language for code execution. Pass as atom.
`timeout`	`:integer`	Execution timeout in seconds.

The response body includes:

Field	Type	Description
`"success"`	`boolean`	Whether execution succeeded.
`"stdout"`	`string \| null`	Standard output from code execution.
`"result"`	`string \| null`	Alias for stdout.
`"stderr"`	`string \| null`	Standard error output.
`"exitCode"`	`integer \| null`	Exit code of executed process.
`"killed"`	`boolean`	Whether process was killed due to timeout.
`"liveViewUrl"`	`string \| null`	Read-only live view of the browser.
`"interactiveLiveViewUrl"`	`string \| null`	Interactive live view.

Call Firecrawl.stop_interactive_scrape_browser_session(job_id) to end the session.

Notes

The Elixir SDK is auto-generated from the OpenAPI spec via mix run generate.exs. Function names match the OpenAPI operation IDs converted to snake_case.
Function names are longer than other SDKs because they follow the OpenAPI operation IDs: scrape_and_extract_from_url (not scrape), search_and_scrape (not search), interact_with_scrape_browser_session (not interact).
All parameters use snake_case in Elixir. The SDK converts to camelCase for the API wire format.
Enum values are passed as atoms: proxy: :auto, language: :node.
All functions return {:ok, %Req.Response{}} or {:error, exception}. Use bang variants (!) to raise instead.
HTTP 4xx/5xx responses are wrapped in Firecrawl.Error with status and body fields.
Parameters are validated at runtime via NimbleOptions. Invalid params return {:error, %NimbleOptions.ValidationError{}}.
The Elixir SDK’s interact_with_scrape_browser_session does not support a prompt parameter (unlike Node.js, Python, and Rust). Use code with the appropriate language.
There are no deprecated aliases in the Elixir SDK.

Source Of Truth

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