List Monitors

1 min read

get/monitor

Request example

curl --request GET \
  --url https://api.firecrawl.dev/v2/monitor \
  --header 'Authorization: Bearer <token>'

Response

{
  "success": true,
  "data": [
    {
      "id": "<string>",
      "name": "<string>",
      "status": "active",
      "schedule": {
        "cron": "<string>",
        "timezone": "<string>"
      },
      "nextRunAt": "2026-08-10T12:00:00Z",
      "lastRunAt": "2026-08-10T12:00:00Z",
      "currentCheckId": "<string>",
      "targets": [
        {
          "id": "<string>",
          "type": "scrape",
          "urls": [
            "<string>"
          ],
          "scrapeOptions": {
            "formats": [
              "markdown"
            ],
            "onlyMainContent": true,
            "onlyCleanContent": false,
            "includeTags": [
              "<string>"
            ],
            "excludeTags": [
              "<string>"
            ],
            "maxAge": 172800000,
            "minAge": 1,
            "headers": {},
            "waitFor": 0,
            "mobile": false,
            "skipTlsVerification": true,
            "timeout": 60000,
            "parsers": [
              "pdf"
            ],
            "actions": [
              {
                "type": "wait",
                "milliseconds": 1
              }
            ],
            "location": {
              "country": "US",
              "languages": [
                "en-US"
              ]
            },
            "removeBase64Images": true,
            "blockAds": true,
            "proxy": "auto",
            "storeInCache": true,
            "lockdown": false,
            "redactPII": false,
            "profile": {
              "name": "<string>",
              "saveChanges": true
            },
            "threatProtection": {
              "mode": "off",
              "riskScoreThreshold": 75,
              "blacklist": [
                "<string>"
              ],
              "whitelist": [
                "<string>"
              ],
              "blockedTlds": [
                "<string>"
              ],
              "failurePolicy": "open"
            },
            "auditMetadata": {
              "username": "<string>"
            }
          }
        }
      ],
      "webhook": {
        "url": "<string>",
        "headers": {},
        "metadata": {},
        "events": [
          "monitor.page"
        ]
      },
      "notification": {
        "email": {
          "enabled": false,
          "recipients": [
            "<string>"
          ],
          "includeDiffs": false
        }
      },
      "retentionDays": 1,
      "estimatedCreditsPerMonth": 1,
      "lastCheckSummary": {
        "totalPages": 1,
        "same": 1,
        "changed": 1,
        "new": 1,
        "removed": 1,
        "error": 1
      },
      "goal": "<string>",
      "judgeEnabled": true,
      "createdAt": "2026-08-10T12:00:00Z",
      "updatedAt": "2026-08-10T12:00:00Z"
    }
  ]
}

get/monitor

Authorization

Authorizationstringheaderrequired#

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

Query parameters

limitinteger#

Default: 25

Range: 1–100

offsetinteger#

Default: 0

Range: >= 0

Responses

application/json

200

List of monitors

successboolean#

dataobject[]#

Show child attributes

idstring#

namestring#

statusenum<string>#

Options:activepauseddeleted

scheduleobject#

Show child attributes

cronstring#

timezonestring#

nextRunAtstring#

lastRunAtstring#

currentCheckIdstring#

targetsobject[]#

Show child attributes

One of

idstring#

Optional stable ID for this target. Generated if omitted.

typeenum<string>required#

Options:scrape

urlsstring[]required#

Items: min 1

scrapeOptionsobject#

Show child attributes

formatsobject[]#

Output formats to include in the response. You can specify one or more formats, either as strings (e.g., 'markdown') or as objects with additional options (e.g., { type: 'json', schema: {...} }). Some formats require specific options to be set. Example: ['markdown', { type: 'json', schema: {...} }].

Default: ["markdown"]

Show child attributes

onlyMainContentboolean#

Only return the main content of the page excluding headers, navs, footers, etc. This is a deterministic HTML-level filter applied before markdown is generated; no LLM is involved.

Default: true

onlyCleanContentboolean#

Beta. Run an additional LLM-based pass over the generated markdown to remove residual boilerplate that onlyMainContent can miss (cookie banners, ad blocks, social share widgets, breadcrumbs, newsletter signups, comment sections, related-article lists). Headings, lists, tables, code blocks, image references, and inline links are preserved. Can be combined with onlyMainContent (the most common setup) or used on its own. Skipped with a warning when the markdown exceeds the cleaning model's output token limit (the original markdown is preserved). Not supported on zero-data-retention requests.

Default: false

includeTagsstring[]#

Tags to include in the output.

excludeTagsstring[]#

Tags to exclude from the output.

maxAgeinteger#

Returns a cached version of the page if it is younger than this age in milliseconds. If a cached version of the page is older than this value, the page will be scraped. If you do not need extremely fresh data, enabling this can speed up your scrapes by 500%. Defaults to 2 days.

Default: 172800000

minAgeinteger#

When set, the request only checks the cache and never triggers a fresh scrape. The value is in milliseconds and specifies the minimum age the cached data must be. If matching cached data exists, it is returned instantly. If no cached data is found, a 404 with error code SCRAPE_NO_CACHED_DATA is returned. Set to 1 to accept any cached data regardless of age.

headersobject#

Headers to send with the request. Can be used to send cookies, user-agent, etc.

waitForinteger#

Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load. This waiting time is in addition to Firecrawl's smart wait feature.

Default: 0

mobileboolean#

Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots.

Default: false

skipTlsVerificationboolean#

Skip TLS certificate verification when making requests.

Default: true

timeoutinteger#

Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds).

Default: 60000

Range: 1000–300000

parsersobject[]#

Controls how files are processed during scraping. When "pdf" is included (default), the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When an empty array is passed, the PDF file is returned in base64 encoding with a flat rate of 1 credit for the entire PDF.

Default: ["pdf"]

Show child attributes

actionsobject[]#

Actions to perform on the page before grabbing the content

Show child attributes

locationobject#

Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified.

Show child attributes

countrystring#

ISO 3166-1 alpha-2 country code (e.g., 'US', 'AU', 'DE', 'JP')

Default: "US"

Pattern: ^[A-Z]{2}$

languagesstring[]#

Preferred languages and locales for the request in order of priority. Defaults to the language of the specified location. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language

removeBase64Imagesboolean#

Removes all base 64 images from the markdown output, which may be overwhelmingly long. This does not affect html or rawHtml formats. The image's alt text remains in the output, but the URL is replaced with a placeholder.

Default: true

blockAdsboolean#

Enables ad-blocking and cookie popup blocking.

Default: true

proxyenum<string>#

Specifies the type of proxy to use.

basic: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.
enhanced: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Billed at the same credit cost as basic.
auto: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. Enhanced proxies carry no credit surcharge, so either way only the regular cost is billed.

Default: "auto"

Options:basicenhancedauto

storeInCacheboolean#

If true, the page will be stored in the Firecrawl index and cache. Setting this to false is useful if your scraping activity may have data protection concerns. Using some parameters associated with sensitive scraping (e.g. actions, headers) will force this parameter to be false.

Default: true

lockdownboolean#

If true, serves the request from Firecrawl's cache only and never makes an outbound request to the target URL. Designed for compliance-constrained or air-gapped environments where the scrape request itself could leak sensitive information. On cache miss, returns a 404 with error code SCRAPE_LOCKDOWN_CACHE_MISS (the URL is never logged on miss). Lockdown requests are treated as zero data retention. Default maxAge is extended to 2 years so existing cached pages remain eligible. Billed at 5 credits on hit, 1 credit on cache miss.

Default: false

redactPIIboolean · object#

Redact personally identifiable information from returned markdown. Pass true to use defaults, or an object to tune mode, entities, and replacement style.

Default: false

Show child attributes

profileobject#

Enable persistent browser storage across scrape and interact sessions. Pass a profile when scraping to preserve cookies, localStorage, and session data. Sessions with the same profile name share browser state.

Show child attributes

namestringrequired#

A name for the profile. Scrapes with the same name share browser state (cookies, localStorage, sessions).

Length: 1–128

saveChangesboolean#

When true, browser state is saved back to the profile when the interact session stops. Set to false to load existing data without writing. Only one saving session is allowed at a time.

Default: true

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

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

idstring#

Optional stable ID for this target. Generated if omitted.

typeenum<string>required#

Options:crawl

urlstringrequired#

crawlOptionsobject#

Crawl options such as limit, maxDepth, includePaths, and excludePaths.

scrapeOptionsobject#

Show child attributes

formatsobject[]#

Default: ["markdown"]

Show child attributes

onlyMainContentboolean#

Only return the main content of the page excluding headers, navs, footers, etc. This is a deterministic HTML-level filter applied before markdown is generated; no LLM is involved.

Default: true

onlyCleanContentboolean#

Default: false

includeTagsstring[]#

Tags to include in the output.

excludeTagsstring[]#

Tags to exclude from the output.

maxAgeinteger#

Default: 172800000

minAgeinteger#

headersobject#

Headers to send with the request. Can be used to send cookies, user-agent, etc.

waitForinteger#

Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load. This waiting time is in addition to Firecrawl's smart wait feature.

Default: 0

mobileboolean#

Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots.

Default: false

skipTlsVerificationboolean#

Skip TLS certificate verification when making requests.

Default: true

timeoutinteger#

Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds).

Default: 60000

Range: 1000–300000

parsersobject[]#

Default: ["pdf"]

Show child attributes

actionsobject[]#

Actions to perform on the page before grabbing the content

Show child attributes

locationobject#

Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified.

Show child attributes

countrystring#

ISO 3166-1 alpha-2 country code (e.g., 'US', 'AU', 'DE', 'JP')

Default: "US"

Pattern: ^[A-Z]{2}$

languagesstring[]#

Preferred languages and locales for the request in order of priority. Defaults to the language of the specified location. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language

removeBase64Imagesboolean#

Default: true

blockAdsboolean#

Enables ad-blocking and cookie popup blocking.

Default: true

proxyenum<string>#

Specifies the type of proxy to use.

basic: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.
enhanced: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Billed at the same credit cost as basic.
auto: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. Enhanced proxies carry no credit surcharge, so either way only the regular cost is billed.

Default: "auto"

Options:basicenhancedauto

storeInCacheboolean#

Default: true

lockdownboolean#

Default: false

redactPIIboolean · object#

Redact personally identifiable information from returned markdown. Pass true to use defaults, or an object to tune mode, entities, and replacement style.

Default: false

Show child attributes

profileobject#

Show child attributes

namestringrequired#

A name for the profile. Scrapes with the same name share browser state (cookies, localStorage, sessions).

Length: 1–128

saveChangesboolean#

When true, browser state is saved back to the profile when the interact session stops. Set to false to load existing data without writing. Only one saving session is allowed at a time.

Default: true

threatProtectionobject#

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

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

idstring#

Optional stable ID for this target. Generated if omitted.

typeenum<string>required#

Options:search

queriesstring[]required#

Search queries to run on each check (1-12).

Items: 1–12

searchWindowenum<string>#

Recency filter — only consider results published within this window.

Default: "24h"

Options:5m15m1h6h24h7d

maxResultsinteger#

Total results to evaluate per check, merged and deduped across all queries (a combined cap, not per-query).

Default: 10

Range: 1–50

includeDomainsstring[]#

Optional. Restrict results to these domains.

Items: max 50

excludeDomainsstring[]#

Optional. Drop results from these domains.

Items: max 50

webhookobject#

Webhook destination for monitor page and check completion events.

Show child attributes

urlstringrequired#

The URL to send monitor webhooks to.

headersobject#

Headers to send to the webhook URL.

Show child attributes

{key}string#

metadataobject#

Custom metadata included in webhook payloads.

eventsenum<string>[]#

Monitor webhook events to receive. Defaults to all monitor events.

notificationobject#

Show child attributes

emailobject#

Show child attributes

enabledboolean#

Default: false

recipientsstring[]#

Items: max 25

includeDiffsboolean#

Include changed page details in email summaries.

Default: false

retentionDaysinteger#

estimatedCreditsPerMonthinteger#

Upper-bound monthly credit estimate. When judging is enabled, actual usage may be lower because judge credits are only charged for changed pages that are judged.

lastCheckSummaryobject#

Show child attributes

totalPagesinteger#

sameinteger#

changedinteger#

newinteger#

removedinteger#

errorinteger#

goalstring#

judgeEnabledboolean#

createdAtstring#

updatedAtstring#

Create Monitor Get Monitor