Firecrawl Elixir Agent Quickstart

Canonical quickstart for external agents. Generated from the firecrawl Elixir SDK source and the v2 OpenAPI spec. Function names are generated from the OpenAPI spec.

Install

Add to mix.exs:

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

Authenticate

# config/runtime.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"
)

When To Use What

search: use when you start with a query and need discovery. Supports site: filtering.
scrape: use when you already have a URL and want page content.
interact: use when the page needs code execution in a browser session after a scrape.

Search

Why use it

Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with site:, for example site:docs.firecrawl.dev crawl webhooks.

Preferred SDK method

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

Example

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

# Results are in res.body["data"]["web"], ["news"], ["images"]

Parameters

Parameter	Type	Description
`query`	string	Required. Search query. Use `site:example.com` to limit to a domain.
`sources`	list	Sources to search: `:web`, `:news`, `:images`, or `%{type: "web"}` maps.
`categories`	list	Filter by category: `:developer`, `:research`, `:pdf`, or typed maps.
`limit`	integer	Cap the number of results.
`tbs`	string	Time-based filter (e.g. `"qdr:d"` for past day).
`location`	string	Localized results (e.g. `"San Francisco,California,United States"`).
`country`	string	ISO country code for geo-targeting (e.g. `"US"`).
`include_domains`	list of strings	Whitelist domains.
`exclude_domains`	list of strings	Blacklist domains.
`ignore_invalid_urls`	boolean	Drop URLs that cannot be scraped.
`highlights`	boolean	Generate query-relevant highlights. Default: `true`.
`timeout`	integer	Request timeout in milliseconds.
`scrape_options`	keyword list	Scrape each search result. Accepts the same fields as scrape params.

Scrape

Why use it

Get structured content from a URL in one or more formats.

Preferred SDK method

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

Example

{:ok, res} = Firecrawl.scrape_and_extract_from_url(
  url: "https://example.com/pricing",
  formats: [
    "markdown",
    %{type: "json", prompt: "Extract plan names and prices."}
  ],
  only_main_content: true
)

# res.body["data"]["markdown"]
# res.body["data"]["json"]

Parameters

Parameter	Type	Description
`url`	string	Required. Page URL to scrape.
`formats`	list	Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"branding"`, `"audio"`, `"video"`. Maps: `%{type: "json", prompt: ...}`, `%{type: "screenshot", fullPage: true}`, `%{type: "changeTracking", modes: ["git-diff"]}`.
`headers`	map	Custom HTTP headers.
`include_tags`	list of strings	Include only these HTML tags.
`exclude_tags`	list of strings	Exclude these HTML tags.
`only_main_content`	boolean	Strip nav, footer, and boilerplate.
`timeout`	integer	Timeout in milliseconds. Min: 1000, max: 300000.
`wait_for`	integer	Wait for page render (milliseconds).
`mobile`	boolean	Use a mobile viewport.
`parsers`	list	File parsing controls. E.g. `%{type: "pdf", mode: "auto", maxPages: 5}`.
`actions`	list of maps	Pre-scrape actions: `wait`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`.
`location`	keyword list	Geo/language targeting: `[country: "US", languages: ["en-US"]]`.
`skip_tls_verification`	boolean	Skip TLS verification.
`remove_base64_images`	boolean	Drop base64 images from markdown.
`block_ads`	boolean	Block ads and cookie popups.
`proxy`	atom or string	Proxy control: `:basic`, `:enhanced`, `:auto`.
`max_age`	integer	Accept cached data up to this age (milliseconds).
`min_age`	integer	Accept cached data only if at least this old (milliseconds).
`store_in_cache`	boolean	Cache the result on Firecrawl’s side.
`profile`	keyword list	Persistent browser profile: `[name: "my-session", save_changes: true]`.
`zero_data_retention`	boolean	Enable zero data retention for this scrape.

Interact

Why use it

Execute code in the browser session tied to a scrape job. The Elixir SDK exposes code-based interactions only (no prompt parameter). code is required.

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, res} = Firecrawl.interact_with_scrape_browser_session(
  job_id,
  code: "console.log(await page.title());",
  language: :node,
  timeout: 60
)

# res.body["stdout"]

# End the session when done
{:ok, _} = Firecrawl.stop_interactive_scrape_browser_session(job_id)

Parameters

Parameter	Type	Description
`job_id`	string	Required. Scrape job ID from scrape response metadata.
`code`	string	Required. Code to run in the browser session.
`language`	atom or string	Runtime: `:python`, `:node`, `:bash`.
`timeout`	integer	Execution timeout in seconds.

Stop session: Firecrawl.stop_interactive_scrape_browser_session(job_id) ends the browser session.

Notes

OpenAPI-generated: Function names and parameter keys are generated from the spec. Do not rename them.
Bang variants: Every function has a ! variant (e.g. scrape_and_extract_from_url!) that raises on error instead of returning {:error, _}.
NimbleOptions validation: Unknown keys cause NimbleOptions.ValidationError before any HTTP call — provides typo detection.
snake_case keys: All Elixir params use snake_case; the SDK auto-converts to camelCase JSON.
Atoms and strings: Enum params like proxy accept both atoms (:auto) and strings ("auto").
Code-only interact: The Elixir SDK does not support prompt on interact — use code only.
No client struct: There is no Firecrawl.Client — configure globally via config :firecrawl or per-call via the opts keyword list.

Source Of Truth

firecrawl/apps/elixir-sdk/mix.exs
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