A Context.dev search monitor (POST https://api.context.dev/v1/monitors with target type "search") runs a web search on a schedule and reports only results it has not seen before, and by default an AI judge keeps only results that describe a new development matching your instructions. You can receive verified change events at your server via signed webhooks or poll changes and runs through the REST API and TypeScript SDK.
Tools used in this guide
- Context.dev Monitors with a search target: scheduled web search that reports new results.
- Context.dev webhooks: signed
change.detectedandrun.completedevents delivered to your endpoint. - Context.dev Highlights (optional): read the relevant passages of a reported article without loading full-page boilerplate into an agent's context window.
What does an API need to do to monitor the web for a topic?
Context.dev search monitors solve the challenge of tracking high-value developments that happen on URLs a team does not know in advance. Watching a single URL is insufficient when new developments appear on unpredictable domains across the web. A naive search and diff script quickly becomes noisy because the same news story is rewritten across dozens of outlets, evergreen pages drift into top rankings, and older articles get re-dated. Developers building a Web Monitoring API for competitive intelligence or news alerts require a system that eliminates this noise. Teams introducing web search monitors to their architecture can effectively track new AI model releases, competitor announcements, security advisories, and regulatory actions.
| Topic Monitoring Requirement | Context.dev Monitors Field or Endpoint | How It Works |
|---|---|---|
| Scheduled web search with operators | target: { type: "search", query } | Runs a query (1 to 500 characters) supporting operators like site:, -site:, and quoted phrases, fetching up to 20 results per run. |
| Baseline capture without false initial alerts | initial_run_id and baseline_created: true | Creating a monitor queues a baseline run right away that records current results and never reports a change. |
| Freshness and URL deduplication | Automatic freshness window and URL tracking | Restricts search to a freshness window covering at least two schedule intervals (last 24 hours, week, month, or year), keeps only URLs not seen within the window, and drops results published before the monitor was created. |
| Filtering out evergreen pages and opinion pieces | target.instructions and change_detection: { type: "semantic", confidence_threshold } | An AI judge checks each new result against your instructions (1 to 2,000 characters), rejecting evergreen pages, opinion pieces, listicles, and duplicates of the last 10 reported changes. |
| Configurable check frequency | schedule: { type: "interval", frequency, unit } | Runs from every 10 minutes to once a year (minutes, hours, or days), defaulting to once a day if omitted. |
| Push notifications or pull polling | webhook: { url, events, retry } or GET /v1/monitors/{monitor_id}/changes | Delivers HMAC-SHA256 signed change.detected and run.completed webhooks, or lets you poll changes per monitor or across your account. |
| Structured evidence for LLM context | matched_urls, matched_url_count, and evidence[] | Provides a judge-written title, summary, and importance (low, medium, high), plus evidence entries holding each reported URL's title and snippet in after. |
| Predictable usage pricing | 2 credits per search monitor run | Baseline runs count, while failed runs, skipped runs, webhook deliveries, and monitor management cost 0 credits. |
Step 1: Create a search monitor
A Context.dev search monitor is created via a single API call to POST https://api.context.dev/v1/monitors using an Authorization header configured with Bearer $CONTEXT_DEV_API_KEY. Using the TypeScript SDK, you begin by importing the client with import ContextDev from "context.dev"; and instantiating it with your API key. You then call await client.monitors.create() and pass an object that defines the name, target, change_detection, schedule, and webhook.
To construct the target object properly, include the type set to "search" and a query string of 1 to 500 characters. This query supports search operators such as site:, -site:, and quoted phrases. You can optionally include instructions up to 2,000 characters to clarify which new results matter and which to ignore.
For example, a monitor might be named "Acme news". Its target could use the query "\"Acme Corp\" -site:acme.com" and instructions like "Alert me when Acme announces an acquisition or a new product. Ignore opinion pieces." The API returns HTTP 201 with the created monitor, showing an id, status of "active", next_run_at, a webhook.secret starting with whsec_, and an initial_run_id. Creating the monitor immediately queues a baseline run. The baseline run records the current results and never reports a change, preventing false alerts on existing data. You can confirm this setup by retrieving the monitor run using its initial_run_id to verify its status is "completed" and baseline_created is true.
Step 2: Write instructions so only real developments are reported
A Context.dev search monitor executes strict filtering and AI evaluation during every run to ensure you only see genuine developments. Each run fetches up to 20 results for your query. These candidates are restricted to a freshness window that covers at least two schedule intervals, selecting the smallest window that fits from the last 24 hours, week, month, or year. Later runs keep only results whose URL has not been seen within that window. Next, the monitor drops any results published before the monitor was created, although results with no publish date are retained.
For the results that pass URL deduplication and publish date checks, the monitor asks the AI judge about each remaining candidate. Under the default semantic detection setting, a result is reported only when it meets all five criteria. First, it describes a concrete development rather than an evergreen page, opinion piece, or listicle. Second, the development happened after monitoring began. Third, it matches your instructions. Fourth, it is not one of the monitor's last 10 reported changes. Fifth, confidence is at or above your configured confidence_threshold.
When a result meets these requirements, the judge writes the change's title, summary, and importance (low, medium, or high). Providing clear, descriptive instructions is the best way to shape the judge's logic. If the judge fails to return verdicts, the run fails with the error code judge_failed.
Step 3: Choose semantic or exact detection
Context.dev search monitors use semantic detection by default for search targets, ensuring that the AI judge validates every candidate result. Adding or omitting instructions on a search target does not change the detection type. If you omit instructions entirely, a semantic search monitor defaults the instructions to the query string itself.
If you prefer to turn the judge off entirely, you can use exact detection. Sending change_detection: { type: "exact" } configures the monitor to report every new result that passes URL deduplication and the post-creation publish date check. In an exact search monitor, the change title is strictly New results for "<query>", and the summary lists up to three result titles.
| Feature | semantic (Default) | exact |
|---|---|---|
| How to enable | Default for search targets, or send change_detection: { type: "semantic", confidence_threshold: 0.8 } | Send change_detection: { type: "exact" } |
Effect of omitting instructions | Stays semantic (instructions default to query) | Stays exact |
| Which new results are reported | Only results describing a concrete development after monitoring began that match instructions, are not in the last 10 changes, and meet confidence_threshold | Every remaining unseen result in the freshness window not published before monitor creation |
Change title and summary | Written by the AI judge | Title is New results for "<query>"; summary lists up to three result titles |
| Extra change fields | importance (low, medium, high) and confidence (0 to 1) | Standard change fields plus matched_urls, matched_url_count, and evidence |
Step 4: Set how often it runs
A Context.dev search monitor runs based on the schedule object you define. You configure the schedule using { type: "interval", frequency, unit }, where the unit can be "minutes", "hours", or "days". Supported ranges span from every 10 minutes up to once a year. Without a schedule parameter, a monitor runs once a day. Each monitor operates at its own fixed slot within the interval, which means the first scheduled run might arrive sooner than one full interval after creation.
You can request an immediate execution at any time by calling POST /v1/monitors/{monitor_id}/run, which returns an HTTP 202 alongside a run_id. Because runs of one monitor never overlap, competing requests are safely queued or rejected. To halt checks, send a PATCH request setting the status to "paused", which will cause any Run now request to return a 409 MONITOR_PAUSED error. Sending a status of "active" resumes checks.
Context.dev also applies automatic pausing rules to protect your system. The platform pauses a monitor automatically after 10 failed runs in a row, 3 failed runs in a row before a baseline exists, or 3 runs in a row skipped for insufficient credits. Failed monitors otherwise keep running on schedule.
Step 5: Receive changes by signed webhook
Context.dev search monitors deliver alerts to your applications via secure webhooks. You configure an endpoint by providing a URL and an array of events. The default event is change.detected, sent only when a run records a validated change, where data.change holds the full change record. You can also subscribe to run.completed, which is sent after every completed run, including baseline runs and runs that find no change. In this case, data.run holds the run record, and data.change holds the change record or null.
Setting webhook.events to ["change.detected", "run.completed"] ensures you receive both. A run that finds a change sends two separate events with distinct IDs. Failed and skipped runs send no webhook, making run.completed useful as a heartbeat. Adding retry: {} turns on the default retry schedule, while omitting it leaves delivery as best effort.
Upon creation, the monitor response returns a webhook.secret that begins with whsec_. Store this secret server side and never log it. Every webhook payload from Context.dev includes an X-Context-Signature header in the form t=<unix seconds>,v1=<hex>. To verify a delivery, you must read the raw request body before parsing the JSON. Ensure the timestamp t is within a strict tolerance window, such as five minutes (300 seconds), to prevent replay attacks. Compute the HMAC-SHA256 hex digest of the string t + "." + rawRequestBody keyed with the full signing secret, and compare the result in constant time. Finally, deduplicate deliveries using the X-Context-Id header, which matches the payload ID and remains identical across replays or retries.
Step 6: Or poll changes through the API
A Context.dev search monitor supports REST API polling if your architecture prefers pulling data instead of receiving webhooks. You can retrieve a specific monitor's changes using GET /v1/monitors/{monitor_id}/changes, which lists changes newest first and supports filtering by tag, since, and until. For an aggregate view, GET /v1/monitors/changes lists changes across all monitors in your organization. The aggregate endpoint accepts filters for monitor_id, target_type, change_detection_type, tag, since, and until.
If you need to inspect execution history to debug failures or review skip reasons, calling GET /v1/monitors/{monitor_id}/runs displays a monitor's past runs. Developers parsing run data can review statuses such as "completed", "failed", or "skipped", and identify precise error codes like judge_failed.
Step 7: Read the change record and pass it to an LLM
A Context.dev search monitor provides a structured payload explicitly designed for programmatic processing or passing directly into a large language model prompt. Every change record includes a title, a summary, the url of the first newly reported result, a detected_at ISO 8601 timestamp, and an array of tags attached to the monitor.
When using semantic detection, the change record also contains an importance rating of "low", "medium", or "high", and a confidence score from 0 to 1. The payload lists newly reported result URLs in matched_urls and provides a count in matched_url_count. Crucially, an evidence array provides one entry per reported result, where each entry's url matches the result and the after object holds the extracted title and snippet. If an agent requires deeper context beyond the search snippet, it can read the relevant passages of a reported article with Context.dev Highlights, a feature detailed in the guide explaining how to add web search to an AI agent.
Complete TypeScript example
A Context.dev search monitor requires two main pieces of code to deploy a complete monitoring pipeline. Part one creates a daily semantic search monitor for a topic with specific instructions, a confidence threshold of 0.8, and a webhook configured with events and retries. This script logs the monitor ID and initial run ID before handing the webhook secret to a storage utility.
Part two demonstrates an Express receiver that securely handles incoming events. The receiver preserves the raw request body with express.raw, verifies the X-Context-Signature using the HMAC-SHA256 hashing algorithm, and securely compares the signatures with crypto.timingSafeEqual. It validates the timestamp to prevent replay attacks and uses a Set to deduplicate webhook events by payload ID. When a validated change is detected, it maps the data into a compact object ready for an LLM prompt.
import ContextDev from "context.dev";
const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });
async function createTopicMonitor() {
const monitor = await client.monitors.create({
name: "Acme news",
target: {
type: "search",
query: "\"Acme Corp\" -site:acme.com",
instructions:
"Alert me when Acme announces an acquisition or a new product. Ignore opinion pieces.",
},
change_detection: {
type: "semantic",
confidence_threshold: 0.8,
},
schedule: {
type: "interval",
frequency: 1,
unit: "days",
},
webhook: {
url: "https://app.example.com/webhooks/context",
events: ["change.detected", "run.completed"],
retry: {},
},
});
console.log("Monitor created:", monitor.id, "Baseline run:", monitor.initial_run_id);
// Save monitor.webhook.secret in your secret manager associated with monitor.id. Never log it.
await saveWebhookSecret(monitor.id, monitor.webhook?.secret);
}curl -X POST https://api.context.dev/v1/monitors \
-H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme news",
"target": {
"type": "search",
"query": "\"Acme Corp\" -site:acme.com",
"instructions": "Alert me when Acme announces an acquisition or a new product. Ignore opinion pieces."
},
"change_detection": {
"type": "semantic",
"confidence_threshold": 0.8
},
"schedule": {
"type": "interval",
"frequency": 1,
"unit": "days"
},
"webhook": {
"url": "https://app.example.com/webhooks/context",
"events": ["change.detected", "run.completed"],
"retry": {}
}
}'import express from "express";
import crypto from "crypto";
const app = express();
const seenEventIds = new Set<string>();
function verifySignature(rawBody: string, header: string | undefined, secret: string): boolean {
if (!header) return false;
const parts = Object.fromEntries(
header.split(",").map((part) => part.split("=") as [string, string])
);
const t = parts.t;
const v1 = parts.v1;
if (!t || !v1) return false;
const timestampSeconds = Number(t);
const nowSeconds = Math.floor(Date.now() / 1000);
if (
!Number.isFinite(timestampSeconds) ||
Math.abs(nowSeconds - timestampSeconds) > 300
) {
return false;
}
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
const expectedBuf = Buffer.from(expected, "hex");
const receivedBuf = Buffer.from(v1, "hex");
if (expectedBuf.length !== receivedBuf.length) return false;
return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}
app.post(
"/webhooks/context",
express.raw({ type: "application/json" }),
async (req, res) => {
const rawBody = (req.body as Buffer).toString("utf8");
const signature = req.header("X-Context-Signature");
const secret = process.env.CONTEXT_WEBHOOK_SECRET || "";
if (!verifySignature(rawBody, signature, secret)) {
return res.status(401).send("Invalid signature");
}
const payload = JSON.parse(rawBody);
if (seenEventIds.has(payload.id)) {
return res.status(200).send("Duplicate event ignored");
}
seenEventIds.add(payload.id);
if (payload.event === "change.detected" && payload.data?.change) {
const change = payload.data.change;
const llmContext = {
title: change.title,
summary: change.summary,
importance: change.importance,
detected_at: change.detected_at,
results: (change.evidence ?? []).map((item: any) => ({
url: item.url,
title: item.after?.title,
snippet: item.after?.snippet,
})),
};
// Pass llmContext to your agent or alerting pipeline
console.log("New topic development:", llmContext);
}
return res.status(200).send("ok");
}
);What it costs
A Context.dev search monitor uses an execution based pricing model where a completed run costs 2 credits. Initial baseline runs count toward this usage at 2 credits, while failed runs and skipped runs are completely free at 0 credits. Secondary operations such as webhook deliveries and monitor management calls (creating, updating, pausing, or listing changes and runs) are also free. Under this system, a daily search monitor operating once per day costs about 60 credits a month. An hourly search monitor running 24 times a day costs about 1,440 credits a month.
Organizations on the free tier receive 1,000 credits a month, which easily covers more than 16 daily search monitors. The number of monitors you can create depends on your organization plan. You can check your plan limits programmatically using GET /v1/monitors/limits, which returns the monitors_used and monitors_limit values. Paused monitors continue to count toward your limit.
Frequently asked questions
Context.dev search monitors frequently power automated agents and alerting systems, leading developers to ask these common implementation questions.
How do I get alerted when there is new web coverage about a topic?
A Context.dev search monitor lets you watch the web for any topic by sending POST https://api.context.dev/v1/monitors with target.type set to "search", your search query, and plain-language instructions. On each scheduled check, the monitor runs the search, filters out previously seen URLs and articles published before monitoring began, and asks an AI judge whether any remaining result describes a new development. When a matching development is found, Context.dev sends a signed change.detected webhook to your server or lets you poll the new results via GET /v1/monitors/{monitor_id}/changes.
How do I stop a monitor from reporting evergreen pages, opinion pieces or listicles?
Context.dev search monitors use semantic detection by default, which passes each unseen result to an AI judge before creating a change. The judge reports a result only when it describes a concrete development that happened after monitoring began, matches your target.instructions, is not among the monitor's last 10 reported changes, and meets your confidence_threshold. You can also use query operators like -site: and quoted phrases in target.query alongside specific exclusions in target.instructions to filter out unwanted domains and commentary.
What is the difference between semantic and exact detection?
A Context.dev search monitor defaults to semantic detection, where an AI judge filters new results against your instructions and writes the change's title, summary, and importance. If you set change_detection: { type: "exact" }, the monitor turns the judge off and reports every unseen result within the freshness window that was not published before the monitor was created. Unlike page targets, adding or omitting instructions on a search target does not change the detection type.
How often can a search monitor run?
A Context.dev search monitor can run on any interval from every 10 minutes to once a year by setting schedule: { type: "interval", frequency, unit } with a unit of "minutes", "hours", or "days". If you omit schedule, the monitor runs once a day at its own fixed slot within the interval. You can also trigger an immediate check at any time by calling POST /v1/monitors/{monitor_id}/run, which returns 202 with a run_id and guarantees that runs of the same monitor never overlap.
How much does a search monitor cost?
A Context.dev search monitor costs 2 credits per completed run, including the initial baseline run, while failed runs, skipped runs, webhook deliveries, and monitor management calls are free. At 2 credits per check, a daily search monitor uses about 60 credits a month and an hourly search monitor uses about 1,440 credits a month. Free organizations receive 1,000 credits a month, and you can check your plan's active and paused monitor allowance at any time with GET /v1/monitors/limits.
A one-line close
A Context.dev search monitor takes just minutes to set up, so get an API key at context.dev and create your first search monitor from the Monitors docs.