Skip to main content
Monitors evaluate changes to extracted page text and notify you through email, signed webhooks, Slack, or a combination. Create and manage them in Dashboard → Monitors, the REST API, SDKs, CLI, or scoped MCP tools.

Create your first monitor

You can create a monitor in the dashboard without an API key. For example, to receive an email when a pricing page changes:
  1. Open Dashboard → Monitors and select New monitor.
  2. Enter a name, such as Pricing changes.
  3. Under Watch, choose Pages and enter the pricing page URL. Enter one URL per line to watch several pages.
  4. Set Refresh to Every day.
  5. Under Monitoring, choose Specific and enter: “Watch for changes to prices, subscription plans, or included usage limits.” Leave Sensitivity at Medium.
  6. Under Notifications, leave Minimum importance at All to receive matching changes regardless of their importance assessment. Enable Email alerts and enter your address.
  7. Select Create monitor, then open the monitor to inspect its settings and history.
Pages monitoring requires Developer or higher (or an internal workspace). The form shows an estimated monthly credit cost based on the number of pages and refresh frequency. See plan limits.
Creating or resuming a monitor sends a “Monitor is active” confirmation through each enabled channel. The first successful Pages check saves a baseline without a change alert. Later checks can trigger change notifications when the extracted page text changes and meets your criteria.

Choose what to watch

Pages accepts 1–100 public HTTP or HTTPS URLs. Choose Every hour, Every 6 hours, Every day, Every week, or Every month. More pages and more frequent checks can consume more crawl credits. The URL list cannot be edited after creation; create a new monitor to watch a different list. For sources and collections, configure refresh through the underlying sources. Creating a monitor does not give those sources a separate refresh schedule. See Collections for organizing the content you want to follow. Monitors evaluate extracted text. General monitoring is designed to detect substantive new, updated, or removed information and ignore presentation changes and temporary interface state.

Choose which changes matter

General or Specific

Choose General to watch for meaningful content changes without writing a description. For example, use it to follow updates across a documentation source. Choose Specific when you have a particular change in mind. Describe the information you care about in What should we watch for?, for example:
  • “Watch for changes to prices, subscription plans, or included usage limits.”
  • “Watch for API deprecations, removed endpoints, or authentication requirement changes.”

Sensitivity

In Specific mode, sensitivity controls how confident the match to your description must be: Start with Medium and inspect the history before adjusting it. A lower API threshold means higher sensitivity.

Minimum importance

Minimum importance is a separate filter that applies to every notification channel, in both General and Specific modes: A change must still meet the monitor’s criteria before it can notify you. All removes the importance filter; it does not alert on every text difference. For the pricing example, start with All, then raise minimum importance if you only want more consequential matching changes.

Choose notification channels

Enable at least one channel. You can combine them:
  • Email alerts: enter up to 10 addresses, separated by commas.
  • Slack: a workspace owner or admin first connects a channel in Settings → Integrations. Return to the monitor and select the connected channel.
  • Webhook: enter a public HTTPS endpoint on port 443. Save the signing secret shown when creating the monitor and use it to verify deliveries.
Email alerts are grouped into one email per monitor per source refresh, after all changes in that refresh have been evaluated. If 50 pages match, you receive one email with added/updated/removed counts, the 10 highest-priority changes with short before-and-after excerpts, and a View all 50 changes link. Each highlighted change links directly to its comparison. A collection monitor sends a separate email for each source refresh. Refreshes with no matching changes send no email; Slack and webhooks continue to notify per matching change. Creating an active monitor or resuming a paused monitor sends Monitor is active immediately through every enabled channel, independently of change filters and minimum importance. This confirms that monitoring is enabled; it does not wait for a crawl or baseline. Editing an already active monitor or pausing it does not send a confirmation. Activation webhooks use the same signature headers as change webhooks, with a distinct payload:
Activation notifications are sent directly after saving the active state. Delivery failures are logged without reverting the monitor or automatically retrying the notification. Change alerts retain their existing delivery retries.

Inspect results and manage the monitor

Open a monitor from Dashboard → Monitors to see its status, Last checked time, settings, and history. Expand View changes on a history entry to inspect the before-and-after content. Comparisons depend on retained page versions, so older content may be unavailable. Use Technical details within an expanded entry to inspect match confidence, importance, channel delivery information, and attempt counts. Failed entries show an error and a Retry action; retrying may send notifications. Under Manage, use Edit to adjust settings or Pause and Resume to control monitoring. Delete removes the monitor and its history. Rotate secret immediately invalidates the old webhook signing secret, so update your receiver when rotating it.

Why didn’t I get an alert?

  1. Check the baseline and timing. A new Pages monitor needs its first successful check before later changes can alert. Check Last checked and the refresh schedule; source and collection monitors depend on source refreshes.
  2. Check whether the monitor is paused. Resume it if you want it to continue monitoring. Resuming Pages monitoring requires access to automatic refresh.
  3. Look for a filtered entry. Expand View changes to see whether the change missed your criteria or fell below minimum importance. Review your Specific description, sensitivity, and importance setting.
  4. Look for a failed check or event. Inspect the displayed error. For failed events, resolve the cause and use Retry if needed; automatic retries also run with backoff.
  5. Check the destination. Confirm email addresses, the connected Slack channel, or the webhook URL. Technical details distinguish channel delivery outcomes. If email was accepted by the provider, check spam and inbox filtering.

Create a monitor programmatically

Use SDK version 0.5.0 or later. See SDK setup for installation and client configuration. Set BULKGRID_API_KEY to an API key with monitors:write; reading settings, history, comparisons, or Slack connections requires monitors:read. For cURL, set BULKGRID_BASE_URL=https://bulkgrid.com. The CLI also uses BULKGRID_API_KEY; browser login does not grant monitor-management permissions. These examples create the same daily pricing monitor as the dashboard walkthrough:
Omit condition to create a General monitor. Both Python clients expose monitors; use await with AsyncBulkgridClient. To watch existing content, replace target with one of these objects: The page target uses an existing document ID; pages accepts URLs and creates recurring crawling. API refresh values for Pages are hourly, six_hourly, daily, weekly, and monthly. For webhook notifications, provide webhook_url and securely store the returned signing_secret. For Slack, use client.monitors.slackConnections() (Python: slack_connections()) to list authorized channels, then set slack_connection_id.

Manage through the SDK

Collection-limited API keys can only access monitors for their permitted collections; they cannot create source-wide or Pages monitors. Reads and writes preserve server-side workspace, membership, and plan checks.

CLI and MCP

The CLI uses BULKGRID_API_KEY; browser login remains search-only.
get, delete, and rotate-secret also accept a monitor UUID. Create and rotate-secret output includes a sensitive signing secret. MCP exposes monitor tools only to API-key connections with mcp:use and the corresponding monitor scope. OAuth connections remain search-only. See MCP tools for names and permissions. Creating a Pages monitor initiates recurring work; retries can send notifications; deletion removes history; secret rotation immediately invalidates the old secret.

Webhooks and retries

Store the signing secret securely when creating or rotating a monitor. Deliveries include webhook-id, webhook-timestamp, and webhook-signature (v1= plus a hexadecimal HMAC-SHA256). Verify the HMAC over eventId.timestamp.rawBody using the secret’s UTF-8 bytes and a constant-time comparison. Reject timestamps more than five minutes from your clock and deduplicate by event ID. Rotation invalidates the old secret immediately, so coordinate your receiver update. Delivery is at least once. Failed evaluation or notification delivery retries up to eight times with backoff; failed events remain inspectable and can be retried manually. SDK and MCP mutations are not automatically retried. Inspect current state before repeating a request whose result is uncertain. Comparisons depend on retained page versions and can report unavailable content.