Elixir - Firecrawl Docs

Scrape single pages, crawl entire sites, and map URLs from your Elixir application. The SDK validates all parameters at runtime with NimbleOptions and uses Req for HTTP, so you get clear errors for typos and invalid options before any request is made.

Every function has a bang (!) variant that raises on error instead of returning {:error, ...} tuples.

Installation#

Add firecrawl to your list of dependencies in mix.exs and configure your API key:

Elixir

# Add to mix.exs{:firecrawl, "~> 1.0"}# Then configure your API key in config.exsconfig :firecrawl, api_key: "fc-YOUR-API-KEY"

Or pass the API key per-request:

Elixir

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

Usage#

Get an API key from firecrawl.dev
Set the API key in your application config or pass it as an option to any function.

Elixir

# Scrape a website:{:ok, scrape_result} = Firecrawl.scrape_and_extract_from_url(  url: "https://firecrawl.dev",  formats: ["markdown", "html"])IO.inspect(scrape_result.body)# Crawl a website:{:ok, crawl_result} = Firecrawl.crawl_urls(  url: "https://firecrawl.dev",  limit: 100,  scrape_options: [    formats: ["markdown", "html"]  ])IO.inspect(crawl_result.body)

Scraping a URL#

Scrape a single URL with scrape_and_extract_from_url. It returns the page content as structured data, including markdown, metadata, and any other formats you request.

Elixir

# Scrape a website:{:ok, result} = Firecrawl.scrape_and_extract_from_url(url: "https://firecrawl.dev", formats: ["markdown", "html"])IO.inspect(result.body)

Crawl a Website#

To crawl a website, use crawl_urls. It takes the starting URL and optional parameters such as page limit, allowed domains, and output format.

Elixir

{:ok, result} = Firecrawl.crawl_urls(url: "https://docs.firecrawl.dev", limit: 5)IO.inspect(result.body)

Start a Crawl#

Start a crawl job and get back the job ID without blocking:

Elixir

{:ok, job} = Firecrawl.crawl_urls(url: "https://docs.firecrawl.dev", limit: 10)crawl_id = job.body["id"]IO.puts(crawl_id)

Checking Crawl Status#

Check the status of a crawl job with get_crawl_status:

Elixir

{:ok, status} = Firecrawl.get_crawl_status("<crawl-id>")IO.inspect(status.body)

Cancelling a Crawl#

Cancel a crawl job with cancel_crawl:

Elixir

{:ok, result} = Firecrawl.cancel_crawl("<crawl-id>")IO.puts("Cancelled: #{inspect(result.body)}")

Map a Website#

Use map_urls to generate a list of URLs from a website:

Elixir

{:ok, result} = Firecrawl.map_urls(url: "https://firecrawl.dev", limit: 10)IO.inspect(result.body)

Search#

Search the web and optionally scrape results:

Elixir

{:ok, result} = Firecrawl.search_and_scrape(query: "firecrawl web scraping", limit: 5)IO.inspect(result.body["data"]["web"])

Batch Scrape#

Scrape multiple URLs in a single batch job:

Elixir

{:ok, result} = Firecrawl.scrape_and_extract_from_urls(  urls: ["https://firecrawl.dev", "https://docs.firecrawl.dev"],  formats: ["markdown"])IO.inspect(result.body)

Agent#

Start an agentic data extraction task:

Elixir

{:ok, job} = Firecrawl.start_agent(  prompt: "Extract all product names and prices",  urls: ["https://example.com/products"])job_id = job.body["id"]# Poll for status{:ok, status} = Firecrawl.get_agent_status(job_id)IO.inspect(status.body)

Browser#

Launch cloud browser sessions and execute code remotely.

Create a Session#

Elixir

{:ok, session} = Firecrawl.create_browser_session(ttl: 600)session_id = session.body["id"]cdp_url = session.body["cdpUrl"]live_view_url = session.body["liveViewUrl"]

Execute Code#

Elixir

{:ok, result} = Firecrawl.execute_browser_code(session_id,  code: ~s(await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)),  language: "python")IO.inspect(result.body)

Profiles#

Save and reuse browser state (cookies, localStorage, etc.) across sessions:

Elixir

{:ok, session} = Firecrawl.create_browser_session(  ttl: 600,  profile: [    name: "my-profile",    save_changes: true  ])

List & Close Sessions#

Elixir

# List active sessions{:ok, sessions} = Firecrawl.list_browser_sessions(status: "active")IO.inspect(sessions.body)# Close a session{:ok, _} = Firecrawl.delete_browser_session(session_id)

Self-Hosted Instances#

To use a self-hosted Firecrawl instance, pass the base_url option:

Elixir

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

Error Handling#

Non-bang functions return {:ok, response} or {:error, exception}. Bang variants raise on error. NimbleOptions validates all parameters before the request is sent, catching typos, missing required fields, and type errors immediately.

Elixir

case Firecrawl.scrape_and_extract_from_url(url: "https://example.com") do  {:ok, response} -> IO.inspect(response.body)  {:error, error} -> IO.puts("Error: #{Exception.message(error)}")end# Or use the bang variant to raise on error:response = Firecrawl.scrape_and_extract_from_url!(url: "https://example.com")IO.inspect(response.body)

All Available Functions#

Function	Description
`scrape_and_extract_from_url`	Scrape a single URL
`scrape_and_extract_from_urls`	Batch scrape multiple URLs
`crawl_urls`	Crawl a website
`get_crawl_status`	Check crawl job status
`get_crawl_errors`	Get crawl job errors
`get_active_crawls`	List active crawls
`cancel_crawl`	Cancel a crawl job
`map_urls`	Map URLs on a website
`search_and_scrape`	Search and scrape results
`start_agent`	Start an agent extraction task
`get_agent_status`	Check agent job status
`cancel_agent`	Cancel an agent job
`create_browser_session`	Create a browser session
`execute_browser_code`	Execute code in a browser session
`list_browser_sessions`	List browser sessions
`delete_browser_session`	Delete a browser session
`get_batch_scrape_status`	Check batch scrape status
`get_batch_scrape_errors`	Get batch scrape errors
`cancel_batch_scrape`	Cancel a batch scrape
`get_credit_usage`	Get remaining credits

Every function above has a bang (!) variant (e.g., scrape_and_extract_from_url!) that raises instead of returning error tuples.

For full API documentation, see hexdocs.pm/firecrawl.