Monitor news, search results and page changes

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 to track position changes.

Create a news monitor

Create a dedicated API key with a monthly limit, then save a query with the Python SDK:

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. 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.

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:

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 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. 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. Scheduled runs do not receive the batch discount.

Related

• Monitors reference: saved fields, response shapes and limits.
• Search filters: domain filters and date controls for realtime searches.
• Spend controls: limits for recurring work.
• Site ingestion: discover and read a larger document set.