> ## Documentation Index
> Fetch the complete documentation index at: https://bulkgrid.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitors

> Watch pages, sources, or collections and receive notifications about meaningful changes.

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](https://bulkgrid.com/docs/plan-gating-and-limits.md).

> [!NOTE]
>
> 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

| Watch | Use it for | Refresh schedule |
| - | - | - |
| **Pages** | Specific URLs, including pages from different websites | Choose a schedule for this monitor |
| **Source** | An existing source | Follows that source's existing schedule |
| **Collection** | Content organized in an existing collection | Follows the schedules of the sources in the collection |

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](https://bulkgrid.com/docs/sources.md#scheduled-refresh). Creating a monitor does not give those sources a separate refresh schedule. See [Collections](https://bulkgrid.com/docs/collections.md) 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:

| Sensitivity | Behavior | API `threshold` |
| - | - | - |
| **High** | More alerts, including less certain matches | `0.65` |
| **Medium** | A balance between broader coverage and clearer matches | `0.8` |
| **Low** | Fewer alerts, only for very clear matches | `0.95` |

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:

| Minimum importance | Changes eligible for notification |
| - | - |
| **All** | Any importance, including changes without an assessment |
| **Low** | Low, Medium, and High |
| **Medium** | Medium and High |
| **High** | High only |

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](#webhooks-and-retries).

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:

```json theme={null}
{
  "id": "activation-uuid",
  "type": "monitor.activated",
  "monitor_id": "monitor-uuid",
  "workspace_id": "workspace-uuid",
  "monitor_name": "Pricing changes",
  "created_at": "2026-11-05T08:00:00+00:00"
}
```

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.

| History status | Meaning |
| - | - |
| **Evaluating** | The change is waiting for or undergoing evaluation |
| **Pending** | The change matched and is awaiting notification delivery |
| **Sent** | Notification delivery completed; email acceptance does not guarantee inbox placement |
| **Filtered** | The change did not meet the monitor's criteria or minimum importance |
| **Evaluation failed** | The change could not be evaluated successfully |
| **Notification failed** | Evaluation completed, but notification delivery failed |
| **Cancelled** | Processing for this event was cancelled |

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](https://bulkgrid.com/docs/sdk.md) 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](https://bulkgrid.com/docs/cli.md) 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:

```js Node.js theme={null}
import { BulkgridClient } from '@bulkgrid/sdk';

const client = new BulkgridClient({
  apiKey: process.env.BULKGRID_API_KEY ?? '',
  baseUrl: 'https://bulkgrid.com',
});

const { monitor } = await client.monitors.create({
  name: 'Pricing changes',
  target: {
    type: 'pages',
    urls: ['https://example.com/pricing'],
    refresh_interval: 'daily',
  },
  condition: 'Watch for changes to prices, subscription plans, or included usage limits.',
  threshold: 0.8,
  email_recipients: ['owner@example.com'],
  minimum_importance: 'all',
});

console.log(monitor.id);
```

```python Python theme={null}
import os
from bulkgrid import BulkgridClient

with BulkgridClient(api_key=os.environ["BULKGRID_API_KEY"]) as client:
    created = client.monitors.create({
        "name": "Pricing changes",
        "target": {
            "type": "pages",
            "urls": ["https://example.com/pricing"],
            "refresh_interval": "daily",
        },
        "condition": "Watch for changes to prices, subscription plans, or included usage limits.",
        "threshold": 0.8,
        "email_recipients": ["owner@example.com"],
        "minimum_importance": "all",
    })
    print(created["monitor"]["id"])
```

```bash cURL theme={null}
curl "$BULKGRID_BASE_URL/api/v1/monitors" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BULKGRID_API_KEY" \
  -d '{
    "name": "Pricing changes",
    "target": {
      "type": "pages",
      "urls": ["https://example.com/pricing"],
      "refresh_interval": "daily"
    },
    "condition": "Watch for changes to prices, subscription plans, or included usage limits.",
    "threshold": 0.8,
    "email_recipients": ["owner@example.com"],
    "minimum_importance": "all"
  }'
```

```bash CLI theme={null}
bulkgrid monitors create --input '{
  "name": "Pricing changes",
  "target": {
    "type": "pages",
    "urls": ["https://example.com/pricing"],
    "refresh_interval": "daily"
  },
  "condition": "Watch for changes to prices, subscription plans, or included usage limits.",
  "threshold": 0.8,
  "email_recipients": ["owner@example.com"],
  "minimum_importance": "all"
}'
```

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:

| Target | API value |
| - | - |
| Source | `{ type: 'source', id: 'SOURCE_UUID' }` |
| Collection | `{ type: 'collection', id: 'COLLECTION_UUID' }` |
| Single indexed document | `{ type: 'page', id: 'DOCUMENT_UUID' }` |

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

| TypeScript | Python | Purpose |
| - | - | - |
| `monitors.list({ offset: 50 })` | `monitors.list({"offset": 50})` | List the next 50 monitors |
| `monitors.get(id)` | `monitors.get(id)` | Settings and last check status |
| `monitors.update(id, { is_active: false })` | `monitors.update(id, {"is_active": False})` | Pause; use true to resume |
| `monitors.events(id, { offset: 0 })` | `monitors.events(id, {"offset": 0})` | History, including filtered and failed events |
| `monitors.comparison(id, eventId)` | `monitors.comparison(id, event_id)` | Before/after page content |
| `monitors.retry(id, { event_id: eventId })` | `monitors.retry(id, {"event_id": event_id})` | Retry a failed event |
| `monitors.rotateSecret(id)` | `monitors.rotate_secret(id)` | Replace webhook signing secret |
| `monitors.delete(id)` | `monitors.delete(id)` | Delete monitor and history |

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.

```bash theme={null}
bulkgrid monitors list --offset 0
bulkgrid monitors events MONITOR_UUID --offset 0
bulkgrid monitors update MONITOR_UUID --input '{"is_active":false}'
bulkgrid monitors comparison MONITOR_UUID EVENT_UUID
bulkgrid monitors retry MONITOR_UUID EVENT_UUID
bulkgrid monitors slack-connections
```

`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](https://bulkgrid.com/docs/mcp-server.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.