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:- Open Dashboard → Monitors and select New monitor.
- Enter a name, such as Pricing changes.
- Under Watch, choose Pages and enter the pricing page URL. Enter one URL per line to watch several pages.
- Set Refresh to Every day.
- Under Monitoring, choose Specific and enter: “Watch for changes to prices, subscription plans, or included usage limits.” Leave Sensitivity at Medium.
- Under Notifications, leave Minimum importance at All to receive matching changes regardless of their importance assessment. Enable Email alerts and enter your address.
- Select Create monitor, then open the monitor to inspect its settings and history.
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.
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?
- 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.
- Check whether the monitor is paused. Resume it if you want it to continue monitoring. Resuming Pages monitoring requires access to automatic refresh.
- 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.
- 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.
- 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. SetBULKGRID_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:
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 usesBULKGRID_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 includewebhook-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.