Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion advanced-scraping-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -464,7 +464,7 @@ Use the `/v2/agent` endpoint for autonomous, multi-page data extraction. The age
| `schema` | `object` | — | JSON schema to structure the extracted data. |
| `maxCredits` | `number` | `2500` | Maximum credits the agent can spend. The dashboard supports up to 2,500; for higher limits, set this via the API (values above 2,500 are always billed as paid requests). |
| `strictConstrainToURLs` | `boolean` | `false` | When `true`, the agent only visits the provided URLs. |
| `model` | `string` | `"spark-1-mini"` | AI model to use. `"spark-1-mini"` (default, 60% cheaper) or `"spark-1-pro"` (higher accuracy). |
| `model` | `string` | `"spark-2"` | AI model to use. `"spark-2"` (default, cheapest and fastest), `"spark-1-mini"` (60% cheaper than Pro) or `"spark-1-pro"` (higher accuracy). |

<CodeGroup>

Expand Down
8 changes: 5 additions & 3 deletions api-reference/v2-openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -2510,11 +2510,12 @@
"model": {
"type": "string",
"enum": [
"spark-2",
"spark-1-mini",
"spark-1-pro"
],
"default": "spark-1-mini",
"description": "The model to use for the agent task. spark-1-mini (default) is 60% cheaper, spark-1-pro offers higher accuracy for complex tasks"
"default": "spark-2",
"description": "The model to use for the agent task. spark-2 (default) is cheaper and faster than both Spark 1 models at comparable accuracy. spark-1-mini is 60% cheaper than spark-1-pro, which offers higher accuracy for complex tasks"
},
"auditMetadata": {
"$ref": "#/components/schemas/AuditMetadata"
Expand Down Expand Up @@ -2635,10 +2636,11 @@
"model": {
"type": "string",
"enum": [
"spark-2",
"spark-1-pro",
"spark-1-mini"
],
"default": "spark-1-pro",
"default": "spark-2",
"description": "Model preset used for the agent run"
},
"error": {
Expand Down
4 changes: 2 additions & 2 deletions developer-guides/usage-guides/choosing-the-data-extractor.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ The `/agent` endpoint is Firecrawl's most advanced offering—the successor to `
- **Autonomous Navigation**: The agent searches and navigates deep into sites to find your data
- **Deep Web Search**: Autonomously discovers information across multiple domains and pages
- **Parallel Processing**: Processes multiple sources simultaneously for faster results
- **Models Available**: `spark-1-mini` (default, 60% cheaper) and `spark-1-pro` (higher accuracy)
- **Models Available**: `spark-2` (default, cheapest and fastest), `spark-1-mini` (60% cheaper than Pro) and `spark-1-pro` (higher accuracy)

### Example

Expand Down Expand Up @@ -204,7 +204,7 @@ result = app.agent(
urls=["https://example.com"], # Optional - can omit entirely
prompt="Extract product information from example.com",
schema=schema,
model="spark-1-mini" # or "spark-1-pro" for higher accuracy
model="spark-2" # default; "spark-1-mini" or "spark-1-pro" also available
)
```

Expand Down
22 changes: 16 additions & 6 deletions features/agent.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -131,18 +131,28 @@ You can share agent runs directly from the Agent playground. Shared links are pu

## Model Selection

Firecrawl Agent offers two models. **Spark 1 Mini is 60% cheaper** and is the default — perfect for most use cases. Upgrade to Spark 1 Pro when you need maximum accuracy on complex tasks.
Firecrawl Agent offers three models. **Spark 2** is the default: cheaper and faster than either Spark 1 model, at comparable accuracy. Both Spark 1 models remain available and unchanged.

| Model | Cost | Accuracy | Best For |
|-------|------|----------|----------|
| `spark-1-mini` | **60% cheaper** | Standard | Most tasks (default) |
| `spark-2` | Lowest | Comparable to Pro | All tasks (default) |
| `spark-1-mini` | **60% cheaper** than Pro | Standard | Cost-sensitive Spark 1 workloads |
| `spark-1-pro` | Standard | Higher | Complex research, critical extraction |

<Tip>
**Start with Spark 1 Mini** (default) — it handles most extraction tasks well at 60% lower cost. Switch to Pro only for complex multi-domain research or when accuracy is critical.
**Spark 2 is the default**, so you can omit the `model` parameter — it costs less and finishes faster than both Spark 1 models on most tasks. The Spark 1 models stay available: among them, start with Mini and switch to Pro only for complex multi-domain research or when accuracy is critical.
</Tip>

### Spark 1 Mini (Default)
### Spark 2 (Default)

`spark-2` is our newest agent model and the default for every request. It handles the full range of tasks that previously called for a Mini-versus-Pro decision, so there is no accuracy-versus-cost trade-off to make.

**Use Spark 2 when:**
- You want the lowest cost per run
- Run time matters
- You would otherwise reach for Spark 1 Pro's accuracy

### Spark 1 Mini

`spark-1-mini` is our efficient model, ideal for straightforward data extraction tasks.

Expand All @@ -164,7 +174,7 @@ Firecrawl Agent offers two models. **Spark 1 Mini is 60% cheaper** and is the de

### Specifying a Model

Pass the `model` parameter to select which model to use:
`spark-2` is the default, so the `model` parameter is optional. Pass it to select a different model:

<CodeGroup>

Expand All @@ -179,7 +189,7 @@ Pass the `model` parameter to select which model to use:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | **Yes** | Natural language description of the data you want to extract (max 10,000 characters) |
| `model` | string | No | Model to use: `spark-1-mini` (default) or `spark-1-pro` |
| `model` | string | No | Model to use: `spark-2` (default), `spark-1-mini`, or `spark-1-pro` |
| `urls` | array | No | Optional list of URLs to focus the extraction |
| `schema` | object | No | Optional JSON schema for structured output |
| `maxCredits` | number | No | Maximum number of credits to spend on this agent task. Defaults to **2,500** if not set. The dashboard supports values up to **2,500**; for higher limits, set `maxCredits` via the API (values above 2,500 are always treated as paid requests). If the limit is reached, the job fails and **no data is returned**. Failed runs are not billed: credits used for AI reasoning are never charged on failure, any credits used for tool calls during the run (scraping, search, mapping, etc.) are refunded, and the response reports `creditsUsed: 0`. |
Expand Down
49 changes: 34 additions & 15 deletions features/models.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "Models"
description: "Choose the right model for your agent extraction tasks."
og:title: "Agent Models | Firecrawl"
og:description: "Choose between Spark 1 Mini and Spark 1 Pro for your agent extraction tasks."
og:description: "Choose between Spark 2, Spark 1 Mini, and Spark 1 Pro for your agent extraction tasks."
sidebarTitle: "Models"
hidden: true
noindex: true
Expand All @@ -13,20 +13,36 @@ import AgentWithModelPython from "/snippets/v2/agent/with-model/python.mdx";
import AgentWithModelJS from "/snippets/v2/agent/with-model/js.mdx";
import AgentWithModelCURL from "/snippets/v2/agent/with-model/curl.mdx";

Firecrawl Agent offers two models optimized for different use cases. Choose the right model based on your extraction complexity and cost requirements.
Firecrawl Agent offers three models optimized for different use cases. Choose the right model based on your extraction complexity and cost requirements.

## Available Models

| Model | Cost | Accuracy | Best For |
|-------|------|----------|----------|
| `spark-1-mini` | **60% cheaper** | Standard | Most tasks (default) |
| `spark-2` | Lowest | Comparable to Pro | All tasks (default) |
| `spark-1-mini` | **60% cheaper** than Pro | Standard | Cost-sensitive Spark 1 workloads |
| `spark-1-pro` | Standard | Higher | Complex research, critical extraction |

<Tip>
**Start with Spark 1 Mini** (default) — it handles most extraction tasks well at 60% lower cost. Switch to Pro only for complex multi-domain research or when accuracy is critical.
**Spark 2 is the default**, so you can omit the `model` parameter — it costs less and finishes faster than both Spark 1 models on most tasks. The Spark 1 models stay available: among them, start with Mini and switch to Pro only for complex multi-domain research or when accuracy is critical.
</Tip>

## Spark 1 Mini (Default)
## Spark 2 (Default)

`spark-2` is our newest agent model and the default for every request. It removes the accuracy-versus-cost decision: it is cheaper and faster than both Spark 1 models while matching Spark 1 Pro's accuracy, and it completes a higher share of runs.

**Use Spark 2 when:**
- You want the lowest cost per run
- Run time matters
- You would otherwise reach for Spark 1 Pro's accuracy
- You have not set `model` at all — this is what you get

**Example use cases:**
- Anything you run on Spark 1 Mini or Spark 1 Pro today
- High-volume extraction where cost per run drives the budget
- Multi-domain research that needs to come back quickly

## Spark 1 Mini

`spark-1-mini` is our efficient model, ideal for straightforward data extraction tasks.

Expand Down Expand Up @@ -60,7 +76,7 @@ Firecrawl Agent offers two models optimized for different use cases. Choose the

## Specifying a Model

Pass the `model` parameter to select which model to use:
`spark-2` is the default, so the `model` parameter is optional. Pass it to select a different model:

<CodeGroup>

Expand All @@ -72,19 +88,20 @@ Pass the `model` parameter to select which model to use:

## Model Comparison

| Feature | Spark 1 Mini | Spark 1 Pro |
|---------|--------------|-------------|
| **Cost** | 60% cheaper | Standard |
| **Accuracy** | Standard | Higher |
| **Speed** | Fast | Fast |
| **Best for** | Most tasks | Complex tasks |
| **Reasoning** | Standard | Advanced |
| **Multi-domain** | Good | Excellent |
| Feature | Spark 2 | Spark 1 Mini | Spark 1 Pro |
|---------|---------|--------------|-------------|
| **Cost** | Lowest | 60% cheaper than Pro | Standard |
| **Accuracy** | Comparable to Pro | Standard | Higher |
| **Speed** | Fastest | Fast | Fast |
| **Best for** | All tasks | Most tasks | Complex tasks |
| **Reasoning** | Advanced | Standard | Advanced |
| **Multi-domain** | Excellent | Good | Excellent |

## Pricing by Model

Both models use dynamic, credit-based pricing that scales with task complexity:
All models use dynamic, credit-based pricing that scales with task complexity:

- **Spark 2**: Uses substantially fewer credits than either Spark 1 model for equivalent tasks
- **Spark 1 Mini**: Uses approximately 60% fewer credits than Pro for equivalent tasks
- **Spark 1 Pro**: Standard credit consumption for maximum accuracy

Expand All @@ -94,6 +111,8 @@ Credit usage varies based on prompt complexity, data processed, and output struc

## Choosing the Right Model

Spark 2 covers both branches below. The tree applies when you are choosing between the two Spark 1 models:

```
┌─────────────────────────────────┐
│ What type of task? │
Expand Down
2 changes: 1 addition & 1 deletion sdks/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -356,7 +356,7 @@ Search and gather data from the web using natural language prompts.
| Option | Description |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `--urls <urls>` | Optional list of URLs to focus the agent on (comma-separated) |
| `--model <model>` | Model to use: `spark-1-mini` (default, 60% cheaper) or `spark-1-pro` (higher accuracy) |
| `--model <model>` | Model to use: `spark-2` (default), `spark-1-mini` (60% cheaper than Pro) or `spark-1-pro` (higher accuracy) |
| `--schema <json>` | JSON schema for structured output (inline JSON string) |
| `--schema-file <path>` | Path to JSON schema file for structured output |
| `--max-credits <number>` | Maximum credits to spend (job fails if limit reached) |
Expand Down
2 changes: 1 addition & 1 deletion snippets/v2/agent/base/curl.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ curl -X POST "https://api.firecrawl.dev/v2/agent" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Extract the main features and benefits of Firecrawl",
"model": "spark-1-mini"
"model": "spark-2"
}'
```

2 changes: 1 addition & 1 deletion snippets/v2/agent/base/js.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const result = await firecrawl.agent({
prompt: "Extract the main features and benefits of Firecrawl",
model: "spark-1-mini"
model: "spark-2"
});

console.log(result.data);
Expand Down
2 changes: 1 addition & 1 deletion snippets/v2/agent/base/python.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ app = Firecrawl(api_key="fc-YOUR_API_KEY")

result = app.agent(
prompt="Extract the main features and benefits of Firecrawl",
model="spark-1-mini"
model="spark-2"
)

print(result.data)
Expand Down
11 changes: 10 additions & 1 deletion snippets/v2/agent/with-model/curl.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
```bash cURL
# Using Spark 1 Mini (default)
# Using Spark 2 (default)
curl -X POST "https://api.firecrawl.dev/v2/agent" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Find the pricing of Firecrawl",
"model": "spark-2"
}'

# Using Spark 1 Mini
curl -X POST "https://api.firecrawl.dev/v2/agent" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
Expand Down
8 changes: 7 additions & 1 deletion snippets/v2/agent/with-model/js.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,13 @@ import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// Using Spark 1 Mini (default - can be omitted)
// Using Spark 2 (default - can be omitted)
const resultSpark2 = await firecrawl.agent({
prompt: "Find the pricing of Firecrawl",
model: "spark-2"
});

// Using Spark 1 Mini
const result = await firecrawl.agent({
prompt: "Find the pricing of Firecrawl",
model: "spark-1-mini"
Expand Down
8 changes: 7 additions & 1 deletion snippets/v2/agent/with-model/python.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,13 @@ from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# Using Spark 1 Mini (default - can be omitted)
# Using Spark 2 (default - can be omitted)
result = app.agent(
prompt="Find the pricing of Firecrawl",
model="spark-2"
)

# Using Spark 1 Mini
result = app.agent(
prompt="Find the pricing of Firecrawl",
model="spark-1-mini"
Expand Down
3 changes: 3 additions & 0 deletions snippets/v2/cli/agent/options.mdx
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
```bash CLI
# Use Spark 2 (the default)
firecrawl agent "Competitive analysis across multiple domains" --model spark-2 --wait

# Use Spark 1 Pro for higher accuracy
firecrawl agent "Competitive analysis across multiple domains" --model spark-1-pro --wait

Expand Down