Agent (Research Preview)

Research Preview

Deep research for data, wherever it is. The Agent API autonomously searches, navigates, and gathers data — no URLs required.

Overview

Agent is the successor to /extract. It finds data in hard-to-reach places using autonomous web navigation. Describe what you need in natural language and the Agent handles the rest.

Agent vs Extract

Feature	Agent (New)	Extract (Legacy)
URLs Required	No	Yes
Speed	Faster	Standard
Cost	Lower	Standard
Reliability	Higher	Standard
Query Flexibility	High	Moderate

Models

Model	Cost	Accuracy	Best For
spark-1-mini	60% cheaper	Standard	Most tasks (default)
spark-1-pro	Standard	Higher	Complex research, critical extraction

Use Mini for: Simple extraction, well-structured sites, high-volume jobs, cost-sensitive work. Use Pro for: Complex competitive analysis, deep reasoning, accuracy-critical, ambiguous data.

Basic Usage

Python

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

# Simple prompt — no URLs needed
result = app.agent(
    prompt="Find the pricing plans for Notion and compare them",
    model="spark-1-mini",
    maxCredits=100
)

print(result.data)

Node.js

import Firecrawl from '@mendable/firecrawl-js';

const app = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const result = await app.agent({
  prompt: "Find the founders of Firecrawl and their backgrounds",
  model: "spark-1-mini",
  maxCredits: 100,
});

console.log(result.data);

Structured Output (Schema)

Use Pydantic models (Python) or JSON Schema to get typed results:

from firecrawl import Firecrawl
from pydantic import BaseModel, Field
from typing import List, Optional

app = Firecrawl(api_key="fc-YOUR-API-KEY")

class Founder(BaseModel):
    name: str = Field(description="Full name of the founder")
    role: Optional[str] = Field(None, description="Role or position")
    background: Optional[str] = Field(None, description="Professional background")

class FoundersSchema(BaseModel):
    founders: List[Founder] = Field(description="List of founders")

result = app.agent(
    prompt="Find the founders of Firecrawl",
    schema=FoundersSchema,
    model="spark-1-mini",
    maxCredits=100
)

for founder in result.data.founders:
    print(f"{founder.name} — {founder.role}")

With Optional URLs

Focus the Agent on specific pages when you know where to look:

result = app.agent(
    urls=["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    prompt="Compare the features and pricing information from these pages",
    model="spark-1-pro"
)

Parameters

Parameter	Type	Required	Description
prompt	string	Yes	Natural language description (max 10,000 chars)
model	string	No	spark-1-mini (default) or spark-1-pro
urls	array	No	Optional URLs to focus the agent
schema	object	No	JSON schema for structured output
maxCredits	number	No	Credit limit cap (default: 2,500)

maxCredits

If the credit limit is hit, the job fails with no data returned — but used credits are still charged. Set this to protect against runaway costs.

Async Pattern (Start & Poll)

For long-running research jobs:

# Start the agent job
agent_job = app.start_agent(
    prompt="Find the top 10 AI startups funded in 2025 with their valuations",
    model="spark-1-pro",
    maxCredits=500
)

print(f"Job ID: {agent_job.id}")

# Check status later
status = app.get_agent_status(agent_job.id)
print(f"Status: {status.status}")  # processing, completed, failed

if status.status == "completed":
    print(status.data)

// Node.js async
const job = await app.startAgent({
  prompt: "Find the top 10 AI startups funded in 2025",
  model: "spark-1-pro",
  maxCredits: 500,
});

const status = await app.getAgentStatus(job.id);
console.log(status.data);

Example Use Cases

Competitive Intelligence

result = app.agent(
    prompt="Find the top 3 AI-powered web scraping competitors, list their key features, pricing, and target audience",
    model="spark-1-pro"
)

Lead Enrichment

class CompanyInfo(BaseModel):
    name: str
    website: str
    employee_count: Optional[str]
    funding: Optional[str]
    tech_stack: List[str]

result = app.agent(
    prompt="Find company information for Vercel, including their tech stack and recent funding",
    schema=CompanyInfo
)

Market Research

result = app.agent(
    prompt="What are the current trends in machine learning frameworks for 2025? Include GitHub stars and community size."
)

Product Comparison

class PricingPlan(BaseModel):
    name: str
    monthly_price: str
    features: List[str]

class Comparison(BaseModel):
    product_a: List[PricingPlan]
    product_b: List[PricingPlan]

result = app.agent(
    prompt="Compare pricing plans between Slack and Microsoft Teams",
    schema=Comparison,
    model="spark-1-pro"
)

CSV Upload (Playground Only)

The Agent Playground at firecrawl.dev/app/agent supports CSV upload for batch processing. Upload a CSV and the Agent processes each row in parallel using Spark-1 Fast parallel agents (10 credits per cell).

Cost

• Dynamic pricing during Research Preview — most runs consume a few hundred credits
• Spark-1 Fast parallel agents: 10 credits per cell (predictable, for CSV batch)
• Free: All users get 5 free daily runs (playground or API)
• maxCredits parameter available to cap spending

API Endpoints

Method	Path	Description
POST	/v2/agent	Start agent job
GET	/v2/agent/{id}	Get agent status
DELETE	/v2/agent/{id}	Cancel agent job

---

Next: Change Tracking →