# Monitor news, search results and page changes

> Schedule search, news and webpage checks with monitors. Read run history, verify signed notifications, manage baselines, pause and resume, and budget recurring checks.

A monitor saves a search, news query or public webpage URL and checks it on a schedule. Use it for new mentions, research updates or a changing release page. Monitors report newly discovered URLs for search and news, or content changes for a webpage; use the [rank tracking guide](https://serpkite.com/docs/guides/rank-tracking) to track position changes.

## Create a news monitor

Create a dedicated [API key](https://serpkite.com/docs/api-keys) with a monthly limit, then save a query with the [Python SDK](https://serpkite.com/docs/sdks#python):

```python
from serpkite import SerpKite

sk = SerpKite()
monitor = sk.monitors.create(
    "ai agents funding",
    endpoint="news",
    name="Agent funding news",
    interval="daily",
    country="us",
    language="en",
    time="day",
    num=10,
    engine="auto",
    metadata={"project": "research"},
)
print(monitor.id, monitor.next_run_at)
```

This example opts into [provider fallback](https://serpkite.com/docs/providers). Send `engine: "google"` when your monitor must stay on Google.

The first run is due immediately. Its results establish the baseline and are all reported as new (`first_run: true` in a webhook). Later runs report URLs they have not previously reported. Changing the saved query or search options resets the baseline, so the next run reports all its results as new again.

`interval` is `hourly`, `daily` (default) or `weekly`. For a different schedule, `interval_seconds` accepts 3,600–2,592,000 seconds and overrides `interval`. `active: false` creates a paused monitor.

## Watch a page instead

For a webpage monitor, use `endpoint: "webpage"` and `url`. Among search options, only `country` is supported; `q`, `language`, `engine` and search filters are rejected.

```bash
curl https://api.serpkite.com/v1/monitors \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint":"webpage",
    "url":"https://docs.python.org/3/whatsnew/index.html",
    "name":"Python release notes",
    "interval":"daily",
    "country":"us"
  }'
```

The first run reports `change: "new"`; a changed page reports `change: "changed"`, its `content_hash` and current `markdown`. Whitespace-only changes do not count as content changes. This is the current page content rather than a line-by-line diff; store the previous version if you need to compute one.

## Read results from the run history

Without a `webhook_url`, new results are kept in the run history. List the newest runs with the SDK:

```python
history = sk.monitors.runs(monitor.id, limit=20)
for run in history.results:
    print(run.id, run.status, run.new_results, run.credits_used)
    for result in run.results or []:
        print(result)

if history.next_before:
    older = sk.monitors.runs(monitor.id, limit=20, before=history.next_before)
```

These statements continue the news-monitor example. The HTTP equivalent is `GET /v1/monitors/{id}/runs?limit=20`, followed by `before=<next_before>` for the next page. History is newest first. Run metadata is kept for 30 days, while each run's result bodies are kept for 24 hours; save the content you need in your own system. `results` can be `null` when there is nothing new or the content has expired.

## Receive signed notifications

Set a `webhook_url` when creating or updating the monitor. Monitors use their own URL; they do not inherit the account's default batch/crawl webhook URL. Each run that finds new results sends a `monitor.results` event with `monitor_id`, `run_id`, `first_run`, `new_results`, `credits_used` and your `metadata`.

Follow [Webhooks](https://serpkite.com/docs/webhooks) to get your account secret and verify the HMAC signature over the timestamp and raw body. Deduplicate with `X-SerpKite-Delivery`, which is the run ID. Monitor delivery tries up to three times per run. Results that could not be delivered remain eligible for delivery in a subsequent run, so make your content processing safe to repeat across run IDs too.

## Pause, resume and run now

| Action | HTTP request | Python SDK |
| --- | --- | --- |
| List monitors | `GET /v1/monitors` | `sk.monitors.list()` |
| Read one | `GET /v1/monitors/{id}` | `sk.monitors.get(id)` |
| Pause | `PATCH /v1/monitors/{id}` with `{"active":false}` | `sk.monitors.update(id, active=False)` |
| Resume | `PATCH /v1/monitors/{id}` with `{"active":true}` | `sk.monitors.update(id, active=True)` |
| Run now | `POST /v1/monitors/{id}/run` | `sk.monitors.run(id)` |
| Delete | `DELETE /v1/monitors/{id}` | `sk.monitors.delete(id)` |

Resuming clears the failure streak and schedules an immediate run. Run now also schedules work for the next scheduler poll, within about 30 seconds, rather than returning search results synchronously. It requires an active monitor; a paused monitor returns `409 invalid_request`.

A monitor pauses after 10 consecutive failed runs or when its API key is revoked. Check `last_status`, `last_error` and `consecutive_failures` before resuming. Updates and run-now calls bind future runs to the calling key, so use the key whose limits you intend the monitor to use.

Search and news monitors store only the options listed in the [monitor reference](https://serpkite.com/docs/endpoints/monitors). Extra fields such as `start_date`, `tbs`, `include_content`, `boost_domains` and `highlights` return `400`; use `time`, `include_domains` and `exclude_domains` for supported filtering.

## Budget recurring checks

Creating and managing a monitor and reading its history are free. Every run is billed like its underlying request, subject to the monitor key's limit and the account's spend cap. A successful check can cost credits even when it finds no *new* results. Failed checks and requests with empty upstream results are free.

A daily 10-result search or news monitor costs at most 30 credits over 30 days for a single provider; hourly checks cost at most 720. A daily webpage monitor costs at most 30 credits over the same period. Search depth and consensus mode increase costs as described in [Credits and billing](https://serpkite.com/docs/credits-and-billing). Scheduled runs do not receive the batch discount.

## Related

- [Monitors reference](https://serpkite.com/docs/endpoints/monitors): saved fields, response shapes and limits.
- [Search filters](https://serpkite.com/docs/search-filters): domain filters and date controls for realtime searches.
- [Spend controls](https://serpkite.com/docs/spend-controls): limits for recurring work.
- [Site ingestion](https://serpkite.com/docs/guides/site-ingestion): discover and read a larger document set.