Skip to main content
Firecrawl is a web scraping and crawling API that turns pages into clean markdown or structured data for LLM applications. Its JSON extraction feature sends the page to a language model and returns data that matches your schema. When you self-host Firecrawl, you choose that model with three environment variables, so a SambaCloud model can do the extraction.
This guide covers self-hosted Firecrawl. Firecrawl’s self-hosting documentation lists connecting your own OpenAI-compatible provider as a self-hosting option, and this guide does not cover Firecrawl Cloud.

Prerequisites

Installation and setup

This guide was tested with Firecrawl v2.11.0. The first start builds the API, Playwright, and database images from source, so it takes longer than later starts.
1

Clone Firecrawl at a release tag

Use a release tag rather than main, so the setup does not change underneath you.
2

Point Firecrawl at SambaCloud

Create a file named .env in the firecrawl folder, next to docker-compose.yaml:
.env
  • OPENAI_API_KEY is your SambaCloud API key. The variable name is Firecrawl’s, not OpenAI’s.
  • OPENAI_BASE_URL is the SambaCloud base URL.
  • MODEL_NAME is a SambaCloud model ID. Firecrawl uses it for every extraction call, whatever model it would otherwise pick.
With USE_DB_AUTHENTICATION=false the Firecrawl API has no authentication. Keep port 3002 on your own machine or a trusted network, and keep the .env file out of version control because it holds your API key.
3

Start Firecrawl

Compose prints several The "..." variable is not set. Defaulting to a blank string warnings for settings this guide does not use. They are harmless. When the build finishes, check that the api service is running:
4

Install the Python client

In a second terminal, create a virtual environment and install requests.
This guide was tested with requests 2.32.5 on Python 3.9.

Extract structured data from a page

The json format takes a JSON schema and an optional prompt. This script asks Firecrawl for the first five books on a sample bookstore page:
extract.py
Output
The script checks for a json field because Firecrawl can return success: true without one when the model call fails. See Troubleshooting.

Choose a model

Firecrawl calls the SambaCloud Responses API (/v1/responses), not chat completions, so only models that support that endpoint work. Each row is the full request time for the script above, changing only MODEL_NAME in .env and running docker compose up -d api to apply it:
MiniMax-M3.1-Flash is a reasoning model. It thinks before it answers, so extraction takes much longer than with gpt-oss-120b. Request times varied widely between runs and over the day, most of all for gemma-4-31B-it, so measure on your own setup before you rely on a number. A plain scrape of the same page, with no model involved, took 1 to 2 seconds. If you extract many pages, set MODEL_NAME to gpt-oss-120b for the fastest results in this test.
Meta-Llama-3.3-70B-Instruct does not support the Responses API on SambaCloud, so Firecrawl cannot use it. Extraction fails quietly instead of returning an error. See the first item in Troubleshooting.

Troubleshooting

Firecrawl scraped the page, but the model call failed, so it dropped the json field and logged the cause. Read the cause from the API logs:
The message in that line names the problem. The next three items are the ones reproduced while writing this guide.
The log shows statusCode 400 and unsupported_model for a request to https://api.sambanova.ai/v1/responses. The model in MODEL_NAME, such as Meta-Llama-3.3-70B-Instruct, is not available on the Responses API. Set MODEL_NAME to one of the models in Choose a model.
The log shows statusCode 401. The OPENAI_API_KEY value is not a valid SambaCloud key. Copy a key from the SambaCloud API keys page, update .env, and run docker compose up -d api.
The log shows statusCode 404. The MODEL_NAME value is not a SambaCloud model ID. See SambaCloud models for the current list.
Compose reads .env when it creates a container. After you edit the file, run docker compose up -d api to recreate the api service with the new values.

Additional resources