firecrawl-monitor

firecrawl monitor

Detect when content on a website changes and get notified by webhook or email. Firecrawl handles fetching, diffing, judging, and notifying server-side. Each page in a check is labeled same, new, changed, removed, or error.

Pick a target mode by what you're watching:

The first three watch URLs you already have. Web search runs your queries each check and alerts on results it hasn't seen before (labeled new once, same on later checks); --goal is required with --queries.

Quick start

# Single page, natural-language schedule, email alert
firecrawl monitor create --name "Blog" --schedule "every 30 minutes" \
  --goal "Alert when a new blog post is published." \
  --page https://example.com/blog \
  --email alerts@example.com
 
# Web monitor — search the whole web for NEW results matching a goal
firecrawl monitor create --name "Competitor launches" --schedule "daily at 9:00" \
  --queries "competitor product launch,competitor funding round" \
  --goal "Alert when a competitor announces a new product or raises funding." \
  --search-window 7d --max-results 20 \
  --email alerts@example.com
 
# Webhook notifications
firecrawl monitor create --name "Docs webhook" --schedule "every 30 minutes" \
  --goal "Alert when docs content changes." \
  --page https://example.com/docs \
  --webhook-url https://example.com/hook \
  --webhook-events monitor.page,monitor.check.completed
 
# Manage and inspect
firecrawl monitor list --limit 20
firecrawl monitor get <monitorId>
firecrawl monitor run <monitorId>             # trigger a check now
firecrawl monitor checks <monitorId>          # list all checks
firecrawl monitor check <monitorId> <checkId> --page-status changed
firecrawl monitor update <monitorId> --state paused
firecrawl monitor delete <monitorId>

Subcommands: create | list | get | update | delete | run | checks | check. Run firecrawl monitor <subcommand> --help for the full option list.

Done when: create returns a monitor ID and a smoke-test run + check confirms the expected target, state, and notification configuration.

Read goals.md when writing or refining --goal (and --queries for web monitors). Read json-tracking.md when the user cares about specific structured fields (price, headline, stock flag) and wants per-field diffs.

Constraints & tips

• Each check uses credits for its underlying scrape, crawl, or search, plus optional judging. See Monitoring pricing.
• Minimum schedule interval is 5 minutes. Monitoring is not available for zero-data-retention teams.
• Prefer one monitor over repeated one-off scrapes whenever the user wants the same URL checked more than once.
• Silence temporarily with update --state paused; reserve delete for monitors that are permanently done. (--state is an update flag; --status is the global CLI status flag.)
• Filter check pages with --page-status changed (or new, removed, error) to skip the noise from same pages.
• firecrawl monitor run <id> triggers a check immediately — useful for smoke-testing a monitor right after creating it.
• --retention-days controls how long snapshots are kept for diffing. Lower it for high-frequency monitors to save storage.
• External email recipients must opt in. First time they're added, Firecrawl sends a confirmation email and they only receive alerts after they confirm. Team-owned addresses are auto-confirmed. Once a recipient unsubscribes, they must be re-added by the owner for a fresh confirmation email.
• On HTTP 429 / rate-limit errors, back off once: wait ~30s and retry once. If it persists, stop, report the rate limit as the blocking reason, and delete any monitors created for this task. Never retry in a loop.
• Monitor-triggered scrapes default maxAge to 0 — every check performs a fresh scrape unless scrapeOptions.maxAge is set explicitly in a JSON payload.

See also

• firecrawl-scrape — one-off scrape; escalate to monitor when checks become recurring
• firecrawl-crawl — one-off crawl; pair with --crawl-url here for recurring crawl diffs
• firecrawl — top-level workflow guide
• firecrawl-build-scrape — building recurring checks into an app instead of running it here