Firecrawl Elixir Agent Quickstart

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

Install

Add to your mix.exs dependencies:

{:firecrawl, "~> 1.9"}

Authenticate

The Elixir SDK does not use a client struct. Authentication is resolved per-call in this order:

:api_key option passed in the trailing opts keyword list of any function call.
Application config: Application.get_env(:firecrawl, :api_key).
If nil or empty, the key is omitted (keyless free tier for scrape, search, and interact).

# Option 1: Pass API key per call
Firecrawl.search_and_scrape([query: "firecrawl"], api_key: "fc-YOUR_API_KEY")

# Option 2: Set in application config (config/config.exs)
config :firecrawl, api_key: "fc-YOUR_API_KEY"

The base URL defaults to https://api.firecrawl.dev/v2 but can be overridden per-call with :base_url in opts.

When To Use What

search_and_scrape — Use when you start with a query and need to discover relevant pages. Returns search results grouped by source type, optionally with scraped content.
scrape_and_extract_from_url — Use when you already have a URL and want its content. Returns markdown, HTML, structured data, screenshots, or other formats.
interact_with_scrape_browser_session — Use when the page needs post-scrape browser actions like clicking, filling forms, or executing code in the browser sandbox.

Search

Why use it

Search the web and optionally scrape each result in one call. Start here when you have a question or topic but not a specific URL.

Preferred SDK function

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

Bang variant: Firecrawl.search_and_scrape!(params, opts) raises on error.

Example

{:ok, %Req.Response{body: body}} =
  Firecrawl.search_and_scrape(
    query: "firecrawl web scraping API",
    limit: 5,
    highlights: true
  )

for result <- body["data"]["web"] || [] do
  IO.puts("#{result["url"]}: #{String.slice(result["markdown"] || "", 0..200)}")
end

Parameters

All parameters are passed as a keyword list. All are optional except query.

Parameter	Type	JSON Key	Description
`query`	`:string`	`query`	Required. The search query.
`limit`	`:integer`	`limit`	Max results to return.
`country`	`:string`	`country`	ISO country code for geo-targeting.
`location`	`:string`	`location`	Geographic location for results.
`tbs`	`:string`	`tbs`	Time-based search filter (e.g. `"qdr:d"` for past day).
`timeout`	`:integer`	`timeout`	Timeout in milliseconds.
`highlights`	`:boolean`	`highlights`	Generate query-relevant highlights.
`categories`	`list`	`categories`	Filter categories (e.g. `"github"`, `"research"`, `"pdf"`).
`enterprise`	`list(string)`	`enterprise`	Enterprise options (e.g. `"anon"`, `"zdr"`).
`exclude_domains`	`list(string)`	`excludeDomains`	Exclude results from these domains.
`include_domains`	`list(string)`	`includeDomains`	Restrict results to these domains. Mutually exclusive with `exclude_domains`.
`ignore_invalid_urls`	`:boolean`	`ignoreInvalidURLs`	Exclude URLs invalid for other Firecrawl endpoints.
`scrape_options`	`:keyword_list`	`scrapeOptions`	Options applied when scraping each result. Uses same keys as `scrape_and_extract_from_url` params.
`sources`	`list`	`sources`	Source types (e.g. `"web"`, `"news"`, `"images"`).

Scrape

Why use it

Fetch and extract content from a single URL. Use when you have a specific page to read.

Preferred SDK function

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

Bang variant: Firecrawl.scrape_and_extract_from_url!(params, opts) raises on error.

Example

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

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

Parameters

All parameters are passed as a keyword list. All are optional except url.

Parameter	Type	JSON Key	Description
`url`	`:string`	`url`	Required. The URL to scrape.
`formats`	`list`	`formats`	Output formats (e.g. `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, `"audio"`, `"video"`).
`actions`	`list`	`actions`	Browser actions before scraping.
`headers`	any	`headers`	Custom HTTP headers.
`include_tags`	`list(string)`	`includeTags`	HTML tags to include exclusively.
`exclude_tags`	`list(string)`	`excludeTags`	HTML tags to exclude.
`only_main_content`	`:boolean`	`onlyMainContent`	Only return main content.
`timeout`	`:integer`	`timeout`	Timeout in milliseconds.
`wait_for`	`:integer`	`waitFor`	Delay in ms before fetching content.
`mobile`	`:boolean`	`mobile`	Emulate a mobile device.
`location`	`:keyword_list`	`location`	Geolocation with `country` and `languages`.
`proxy`	`:basic \| :enhanced \| :auto`	`proxy`	Proxy mode.
`block_ads`	`:boolean`	`blockAds`	Block ads and cookie popups.
`max_age`	`:integer`	`maxAge`	Use cached result if younger than this (ms).
`min_age`	`:integer`	`minAge`	Minimum cache age (ms).
`parsers`	`list`	`parsers`	File processing parsers.
`profile`	`:keyword_list`	`profile`	Persistent browser profile.
`redact_pii`	`:boolean`	`redactPII`	Redact personally identifiable information.
`remove_base64_images`	`:boolean`	`removeBase64Images`	Remove base64 images from output.
`skip_tls_verification`	`:boolean`	`skipTlsVerification`	Skip TLS certificate verification.
`store_in_cache`	`:boolean`	`storeInCache`	Whether to cache the result.
`lockdown`	`:boolean`	`lockdown`	Serve only cached results.
`zero_data_retention`	`:boolean`	`zeroDataRetention`	Enable zero data retention.
`audit_metadata`	`:keyword_list`	`auditMetadata`	User attribution with required `username` key.

Interact

Why use it

Execute code in the browser sandbox associated with a scrape job. Use after a scrape to click buttons, fill forms, navigate, or extract additional data.

Preferred SDK function

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

Bang variant: Firecrawl.interact_with_scrape_browser_session!(job_id, params, opts) raises on error.

Example

{:ok, %Req.Response{body: scrape_body}} =
  Firecrawl.scrape_and_extract_from_url(
    url: "https://example.com",
    formats: ["markdown"]
  )

job_id = scrape_body["data"]["metadata"]["jobId"]

{:ok, %Req.Response{body: result}} =
  Firecrawl.interact_with_scrape_browser_session(job_id,
    code: "document.querySelector('button.load-more')?.click();",
    language: :node,
    timeout: 30
  )

IO.puts(result["stdout"])

Parameters

Parameter	Type	JSON Key	Description
`job_id`	`String.t()`	URL path	Required (positional). The scrape job ID.
`code`	`:string`	`code`	Required. Code to execute in the browser sandbox.
`language`	`:python \| :node \| :bash`	`language`	Runtime language.
`timeout`	`:integer`	`timeout`	Execution timeout in seconds.
`origin`	`:string`	`origin`	Request origin tag.

Firecrawl.stop_interactive_scrape_browser_session(job_id, opts \\ [])

Stops the interactive browser session.

Notes

Naming style: Parameters use snake_case in Elixir and are serialized to camelCase JSON keys internally.
OpenAPI-shaped client: The Elixir SDK is generated from the OpenAPI spec, so function names directly mirror operation IDs (search_and_scrape, scrape_and_extract_from_url, interact_with_scrape_browser_session).
Return type: All functions return {:ok, %Req.Response{}} | {:error, Exception.t() | Firecrawl.Error.t()}. Bang variants raise on error.
No prompt parameter: Unlike the JS, Python, and Rust SDKs, the Elixir SDK’s interact function does not support a prompt parameter. Use code only.
Per-call auth: Every function accepts :api_key and :base_url in the trailing opts keyword list, allowing different credentials per call.

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

Agent Quickstarts

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

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

​Related function

​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

Related function

Notes

Source Of Truth