Agent

1 min read

post/agent

Request example

curl --request POST \
  --url https://api.firecrawl.dev/v2/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "urls": [
    "<string>"
  ],
  "prompt": "<string>",
  "schema": {},
  "maxCredits": 1,
  "strictConstrainToURLs": true,
  "model": "spark-2",
  "effort": "low",
  "webhook": {
    "url": "<string>",
    "headers": {},
    "metadata": {},
    "events": [
      "started",
      "action",
      "completed",
      "failed",
      "cancelled"
    ]
  },
  "auditMetadata": {
    "username": "<string>"
  },
  "threatProtection": {
    "mode": "off",
    "riskScoreThreshold": 75,
    "blacklist": [
      "<string>"
    ],
    "whitelist": [
      "<string>"
    ],
    "blockedTlds": [
      "<string>"
    ],
    "failurePolicy": "open"
  }
}'

Response

{
  "success": true,
  "id": "<string>"
}

post/agent

Are you an AI agent that needs a Firecrawl API key? See firecrawl.dev/agent-onboarding/SKILL.md for automated onboarding instructions.

Authorization

Authorizationstringheaderrequired#

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Body

application/json

urlsstring[]#

Optional list of URLs to constrain the agent to

promptstringrequired#

The prompt describing what data to extract

Length: max 10000

schemaobject#

Optional JSON schema to structure the extracted data

maxCreditsnumber#

Maximum credits to spend on this agent task. Defaults to 2500 if not set. Values above 2,500 are always billed as paid requests.

strictConstrainToURLsboolean#

If true, agent will only visit URLs provided in the urls array

modelenum<string>#

The model to use for the agent task. spark-2 is the default and the model every run executes on. The Spark 1 model names remain accepted for backwards compatibility but are deprecated and route to spark-2.

Default: "spark-2"

Options:spark-2spark-1-minispark-1-pro

effortenum<string>#

Reasoning budget for the agent task. Every run executes on spark-2, so effort can be sent with or without model.

Options:lowmediumhigh

webhookobject#

A webhook specification object. Subscribes to agent lifecycle events (agent.started, agent.action, agent.completed, agent.failed, agent.cancelled).

Show child attributes

urlstringrequired#

The URL to send webhook events to.

headersobject#

Headers to send to the webhook URL.

Show child attributes

{key}string#

metadataobject#

Custom metadata that will be included in all webhook payloads for this agent job.

Show child attributes

{key}string#

eventsenum<string>[]#

The events to send to the webhook URL. Defaults to all events.

Default: ["started","action","completed","failed","cancelled"]

auditMetadataobject#

User attribution included with SIEM logging events when SIEM Logging is enabled for the organization.

Show child attributes

usernamestringrequired#

The username associated with the request.

Length: max 1024

threatProtectionobject#

Per-request Threat Protection override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, mode may not be set to off.

Show child attributes

modeenum<string>#

URL scanning mode for this request. normal checks URLs against Google Web Risk (+2 credits per URL scanned).

Options:offnormal

riskScoreThresholdinteger#

Normalized risk score (0–100) at or above which a classifier verdict blocks the URL. Lower is stricter.

Range: 0–100

blackliststring[]#

Domains to always block, as plain domains (example.com) or wildcard globs (*.example.com). No protocol, path, or port.

Items: max 1000

whiteliststring[]#

Domains to always allow, as plain domains or wildcard globs. Wins over every other rule.

Items: max 1000

blockedTldsstring[]#

Top-level domains to block outright, lowercase without the leading dot (e.g. zip).

Items: max 1000

failurePolicyenum<string>#

What to do when the classifier can't be reached: closed blocks the request, open allows it.

Options:openclosed

Responses

application/json

Agent task started successfully

successboolean#

idstring#

Get Monitor Check List Agent Runs