/monitor to watch known pages, crawl a website on a schedule, or run an always-on web search for new results that match a goal.
All monitor types share the same workflow: choose one or more targets, set a schedule, add an optional plain-language goal, and receive webhook, email, or Slack notifications when something matters. This page covers shared configuration. For target-specific setup and examples, go to the Page, Website, or Entire web-scale monitoring page.
Page monitoring
Watch one or more known URLs, diff each scrape against the last snapshot, and alert on meaningful page changes.
Website monitoring
Crawl a site on a schedule, detect added, changed, or removed pages, and notify your webhook or inbox.
Entire web-scale monitoring
Run recurring web searches and alert when a new result appears that matches your goal.
same, new, changed, removed, or error. You can receive a webhook as each monitored page finishes, a webhook for every completed check, email summaries when changes or errors happen, Slack notifications to a channel, or any combination of those notifications.
Targets
Every monitor has one or more targets. The target type determines what each check does:
Each monitor accepts 1–50 targets, and you can mix target types in a single monitor.
retentionDays defaults to 30 and can be set up to 365.
Every create call returns the new monitor with its normalized cron, computed nextRunAt, and estimatedCreditsPerMonth. When judging is enabled, estimatedCreditsPerMonth is an upper-bound estimate because judge credits are only charged for changed pages that are actually judged:
Response
Goals and judging
Add a plain-languagegoal when you only want to be alerted for meaningful changes. If goal is present and judgeEnabled is omitted, Firecrawl enables judging automatically. Judging runs on changed pages and returns a judgment with meaningful, confidence, reason, and meaningfulChanges.
How the goal is applied depends on the target: page and website monitors judge changed pages, while entire web-scale monitors judge each new search result.
Use judgeEnabled: false if you want to store a goal without judging changes yet. The judge only runs when the monitor has both judgeEnabled and a non-empty goal.
A
goal is required for search targets (entire web-scale monitoring) unless you set judgeEnabled: false. It is optional for scrape and crawl targets.Each check always charges for the underlying scrapes or crawls. If judging is enabled, the judge adds 1 credit for each changed page it validates. Checks with no changed pages do not use judge credits.
monitor.page webhook like this when a matching story enters scope:
monitor.page
Schedules
Schedules can be provided as cron or as simple natural language text.every 30 minutesevery 15 minutes starting at :07hourlyevery 2 hoursdailydaily at 9:00daily at 9amdaily at 5:30 PMweekly
timezone controls when phrases like daily at 9am run. Text schedules are spread by monitor ID before they are converted to cron so many monitors do not all run at the same instant.
Change tracking
Page and website monitors diff each page’s markdown by default and reportsame, changed, new, removed, or error. When you want to detect changes in specific structured fields (price, headline, in-stock flag, the items in a list, etc.), enable JSON-mode change tracking by adding a changeTracking format with modes: ["json"] to the target’s scrapeOptions.
Change tracking applies to
scrape and crawl targets. Entire web-scale (search) monitors alert on new results rather than diffing known pages. See Statuses and dedup.Markdown mode (default)
WhenscrapeOptions.formats is just ["markdown"], each changed page in the check response carries a unified text diff plus a parseDiff-style AST:
Markdown-mode diff
JSON mode
Pass achangeTracking format with modes: ["json"] together with a JSON schema (or a prompt) describing the fields you care about. Firecrawl extracts that JSON on every check and emits a per-field diff keyed by the field path, plus a snapshot.json with the full current extraction so consumers don’t need to re-fetch the underlying scrape.
{previous, current} pair:
JSON-mode diff
Even if no tracked field changed but the surrounding markdown did, JSON-mode monitors still report
same unless you also enable git-diff (see mixed mode below). The diff focuses purely on the fields in your schema.Mixed mode (JSON + git-diff)
If you want both the structured per-field diff and the raw markdown unified diff, pass both modes:Mixed target (JSON + git-diff)
diff.text (markdown sidecar) and diff.json (per-field diff), along with the snapshot.json extraction:
Mixed-mode diff (JSON + git-diff)
changed whenever either surface changed.
Notifications
Webhooks
When a monitor has awebhook, Firecrawl can send two monitor events:
monitor.page: Sent as each monitored scrape finishes in the scrape worker.monitor.check.completed: Sent after the full check is reconciled. Includes check status and summary counts. Usemonitor.pageevents or the monitor check API for page-level results.
monitor.page includes isMeaningful and judgment when meaningful-change judging ran for a changed page.
Webhook config
monitor.page payload:
monitor.page
monitor.check.completed payload:
monitor.check.completed
success is true when the check completed without page errors. It is false for failed or partial checks, and error contains the failure reason when available.
Email config
recipients is omitted, Firecrawl sends to team members who are eligible for system alert emails.
You can configure up to 25 explicit recipients.
Recipient confirmation process
When a new recipient is added to a monitor, Firecrawl sends them an email containing a confirmation link. This ensures they explicitly agree to receive notifications for that monitor. If the recipient is already a member of the team, no confirmation is required.Slack
You can also have monitor notifications delivered to a Slack channel.Slack notifications are a dashboard-only feature. They can only be configured through the monitoring dashboard, not through the API or SDKs.
- Open the monitoring dashboard. You can add Slack notifications while creating a new monitor, or add them to a monitor that already exists.
- During monitor creation, or once you’ve selected an existing monitor, scroll to Notifications and select Slack.
- You’ll be prompted to proceed through OAuth. Complete the flow and select the workspace and channel you want to receive notifications in.
Check results
UseGET /v2/monitor/{monitorId}/checks to list checks and GET /v2/monitor/{monitorId}/checks/{checkId} to inspect a check. The SDKs auto-paginate by default.
status: queued, running, completed, failed, partial, or skipped_overlap.
The check detail response includes estimatedCredits, actualCredits, summary counts, and a paginated pages array. estimatedCredits is the upper-bound reservation for the check; actualCredits is the final amount charged after Firecrawl knows how many pages changed and needed judging. Use the top-level next URL to fetch the next page of results, matching crawl pagination. You can filter pages by status: same, new, changed, removed, or error. Each changed page includes inline diff data; pages from JSON-mode monitors also include a snapshot with the current extraction.
- Markdown mode
- JSON mode
- Mixed mode
Markdown-mode response

