Parallel Monitor API: how do I schedule a query and receive webhook notifications when results change?

Most teams discover they need the Monitor API once a one-off search isn’t enough. You don’t just want to know what’s on the web right now—you want to know the moment something important changes, and you want your agents or workflows to react automatically via webhooks.

This guide walks through how to use Parallel’s Monitor API to (1) define a scheduled query, and (2) receive webhook notifications when new events are detected. I’ll assume you’re building for agents or backend workflows, not humans clicking in a dashboard, and you care about predictable costs and evidence-backed outputs.

What the Monitor API actually does

Parallel’s Monitor API turns a natural-language monitoring objective into a continuous “watcher” over the web:

You define what to track (e.g., “new SOC2 reports for top LLM vendors,” “product release notes for Stripe,” “new AI safety policies from EU regulators”).
You choose how often to check (hourly, daily, weekly).
Parallel runs asynchronous crawls and detection passes over its AI-native web index and live web.
When it finds new events, it emits structured outputs with citations via the Basis framework, so every detected change is traceable back to source URLs.

Key properties:

Price: $0.003 per request (≈ $3 CPM / 1K requests).
Frequency: Hourly / daily / weekly schedules.
Latency: Asynchronous (new events arrive after each run, not in a sub‑5s search call).
Rate limits: 300 requests/min.
Basis: Citations for verifiability on each event.

From an architecture standpoint, Monitor is how you push “watch this over time” into Parallel’s infrastructure instead of trying to glue search + scrape + diff logic together yourself.

Core concepts: monitors, runs, and events

Before wiring webhooks, it helps to pin down the main objects you’ll work with:

Monitor definition
The configuration describing what to watch and how often. Think fields like:
- query or objective: natural-language description of the monitoring task.
- frequency: hourly, daily, or weekly.
- filters (optional): domain constraints, regions, or topic hints.
- webhook_url: where Parallel should POST new events.
- metadata (optional): anything you want echoed back in webhook payloads.
Monitor run
Each time the schedule triggers, Parallel executes a run:
- Executes searches + live crawling based on your objective.
- Compares current state of relevant pages/entities against prior state.
- Emits new events only when something has changed.
Event
A structured JSON object describing the change, with:
- Summary of the change (e.g., “New SOC 2 report published”).
- Core fields (title, entity, category, timestamp).
- Citations (URLs + snippets) so you can verify programmatically.
- In many setups, a stable event_id for de‑duplication.

Your webhook handler is essentially an event consumer.

Typical use cases for scheduled monitoring

The Monitor API is designed for agent workflows that need fresh, evidence-backed web signals without continuous polling:

Regulatory and policy tracking
“Monitor the web for new AI policy proposals from EU, US, and UK regulators.”
Vendor and competitor updates
“Watch for product release notes, SLAs, and SOC2 status changes for my vendor list.”
AI research monitoring
“Track new breakthroughs in AI research on arXiv, NeurIPS, ICML, and key lab blogs.”
Security & trust signals
“Alert me when a vendor’s status page reports a new incident or they change their privacy policy.”

In each case, you want:

Low operational overhead (no DIY diff logic).
Evidence-based outputs (citations and rationale).
Predictable costs (CPM-style pricing vs unbounded browsing tokens).

Step 1: Design your monitoring objective

Start by writing the monitoring objective in the same natural-language style you’d use for Parallel’s Task or FindAll APIs, but with a “watch over time” intent.

Examples:

“Monitor any new SOC 2 or security certifications for Anthropic, OpenAI, and Google DeepMind.”
“Track new feature releases and pricing changes for Stripe Billing and Paddle.”
“Monitor for new AI safety guidelines and standards from NIST, ISO, and ENISA.”

Good objectives:

Are specific about entities: company names, regulators, product lines.
Mention event types: “new policy,” “release notes,” “outage,” “security incident,” “M&A.”
Avoid trying to encode logic into keywords—let Parallel’s AI-native index and processors handle retrieval and change detection.

You can prototype these directly in the Monitor playground:
https://platform.parallel.ai/play/monitor
Then translate a successful configuration into API calls.

Step 2: Configure schedule and processor

Next, decide how often to run and what depth of processing you need.

Frequency
- hourly if your use case is latency-sensitive (e.g., incident response, trading signals).
- daily for most vendor, policy, and research tracking.
- weekly for slower-moving domains.
Processor choice (architecture)
Under the hood, Monitor runs on a processor tier comparable to the Search/Task stack:
- More compute enables deeper cross-referencing, better recall, and more robust change detection.
- Lower tiers prioritize cost and latency.

In practice:

Start with the default Monitor processor unless you have evidence you need a heavier tier.
If your events are high-value (e.g., model governance, regulated workflows), it’s worth trading some latency for higher confidence and recall.

Because Monitor pricing is per request (not per token), you can forecast spend precisely:

Example: 10 monitors × daily frequency
→ 10 requests/day → 300 requests/month → ≈ $0.90/month at $3 CPM.
Scaling to 1,000 monitors daily
→ 1,000 requests/day → 30,000/month → ≈ $90/month.

This is the economic posture I recommend: predict request volume; forecast CPM; set budgets before you deploy.

Step 3: Create a monitor via API

Here’s a conceptual example of how you might define a monitor in code. The exact schema may vary, but the pieces are consistent: objective, frequency, and webhook.

curl -X POST "https://api.parallel.ai/v1/monitor" \
  -H "Authorization: Bearer $PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Monitor any new SOC 2, ISO 27001, or major security policy updates for Anthropic, OpenAI, Google, and Microsoft Azure.",
    "frequency": "daily",
    "webhook_url": "https://your-service.com/webhooks/parallel-monitor",
    "filters": {
      "domains": ["anthropic.com", "openai.com", "cloud.google.com", "azure.microsoft.com", "trust.openai.com"]
    },
    "metadata": {
      "group": "vendor-security",
      "owner": "risk-team",
      "priority": "high"
    }
  }'

Expected response (simplified):

{
  "monitor_id": "mon_abc123",
  "objective": "Monitor any new SOC 2, ISO 27001, or major security policy updates...",
  "frequency": "daily",
  "webhook_url": "https://your-service.com/webhooks/parallel-monitor",
  "status": "active",
  "created_at": "2026-04-01T12:34:56Z",
  "metadata": {
    "group": "vendor-security",
    "owner": "risk-team",
    "priority": "high"
  }
}

Once the monitor is active, Parallel will schedule runs at the configured cadence and POST new events to your webhook.

Step 4: Understand the webhook payload

When Monitor detects new events in a run, it sends an HTTP POST to your webhook_url. The payload will be a JSON object you can parse programmatically. A representative shape looks like this:

{
  "monitor_id": "mon_abc123",
  "run_id": "run_2026-04-02",
  "run_timestamp": "2026-04-02T01:05:00Z",
  "objective": "Monitor any new SOC 2, ISO 27001, or major security policy updates...",
  "metadata": {
    "group": "vendor-security",
    "owner": "risk-team",
    "priority": "high"
  },
  "events": [
    {
      "event_id": "evt_001",
      "summary": "OpenAI published an updated SOC 2 Type 2 report on trust.openai.com.",
      "entity": "OpenAI",
      "category": "security_certification",
      "detected_at": "2026-04-02T01:04:12Z",
      "properties": {
        "certification_type": "SOC 2 Type 2",
        "valid_through": "2027-02-01",
        "report_url": "https://trust.openai.com/soc2"
      },
      "basis": {
        "citations": [
          {
            "url": "https://trust.openai.com",
            "snippet": "OpenAI SOC 2 Type II report now available..."
          }
        ],
        "confidence": 0.93,
        "rationale": "Detected new SOC 2 report link added to trust.openai.com and verified page contents."
      }
    }
  ]
}

Important properties from a system design standpoint:

monitor_id / run_id — helps you trace back to configuration and debug schedules.
metadata — echoes your metadata for routing (e.g., owner: risk-team).
events array — may be empty if no changes were found.
basis block — this is Parallel’s Basis framework:
- citations: where the information came from, with snippets.
- confidence: calibrated confidence per event or field.
- rationale: a concise explanation of how the change was inferred.

In production, treat basis as first-class data, not just decoration. It’s what lets you build evidence-based gating logic: promote high-confidence events; flag or review low-confidence ones.

Step 5: Implement a robust webhook receiver

To reliably consume monitor events, build your webhook handler with four core behaviors:

Verify authenticity
- Use a secret, token, or signature (e.g., HMAC over payload) to ensure the POSTs are from Parallel.
- Reject requests that fail signature checks.
Handle at-least-once delivery
Parallel may retry on failure (network issues, 5xx responses). Design your handler to be idempotent:
- Use event_id or a (monitor_id, run_id) combination to detect duplicates.
- Store processed IDs in a fast datastore (Redis, key-value store).
Acknowledge quickly
- Parse and enqueue the work, then return 200 OK within a short time window.
- Do heavy processing asynchronously (via a queue, background workers, or an event bus).
Route by metadata
Use the metadata you attached at monitor creation to route events:
- group: vendor-security → send to risk Slack channel + ticketing system.
- priority: high → trigger PagerDuty or equivalent.
- owner: research-team → write into a research knowledge base.

Example pseudo-code (Node.js/Express-style):

app.post('/webhooks/parallel-monitor', async (req, res) => {
  const signature = req.headers['x-parallel-signature'];
  const rawBody = req.rawBody; // ensure you capture raw for verification

  if (!verifySignature(rawBody, signature, process.env.PARALLEL_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const payload = req.body;

  // Idempotency check
  if (await hasProcessedRun(payload.run_id)) {
    return res.status(200).send('Already processed');
  }

  await markRunAsProcessed(payload.run_id);

  // Enqueue processing of each event
  for (const event of payload.events || []) {
    await enqueueEvent({
      monitorId: payload.monitor_id,
      runId: payload.run_id,
      metadata: payload.metadata,
      event
    });
  }

  res.status(200).send('OK');
});

Step 6: Use Basis (citations & confidence) in downstream logic

This is the part most teams underutilize. Because Monitor uses Parallel’s Basis framework, every event comes with citations and calibrated confidence. You can treat these as programmable constraints:

Confidence thresholds
- Example: Auto-create tickets for confidence >= 0.9; send to human review for 0.7–0.9; discard or log only below 0.7.
- This is where Parallel’s “verifiability and provenance” stance pays off; you aren’t forced to blindly trust every atomic fact.
Citation-based validation
- You can re-fetch cited URLs using Parallel’s Extract API if the event is high-value:
  - Verify that the claimed change appears in the compressed excerpt or full contents.
  - Run additional policy checks on the source page.
Audit trails
- Store basis.citations and basis.rationale alongside any internal records you create.
- In regulated environments, this gives you auditable provenance: you can explain exactly which web artifacts justified a decision.

Step 7: Manage and update monitors over time

Once you have monitors in production, treat them like infrastructure:

List monitors
- Add a simple admin endpoint or internal tool to call GET /monitor and see:
  - monitor_id, objective, frequency, webhook_url, status.
  - Last run time and last event count.
Update monitors
- If your use case evolves, update:
  - frequency (e.g., daily → hourly).
  - objective (e.g., add a new vendor).
  - webhook_url (e.g., move to a new service).
- Use PATCH /monitor/{monitor_id} or equivalent.
Pause or delete monitors
- If you no longer need a stream, deactivate it rather than letting it silently generate events.
- “Pause” can be useful for temporary freezes (e.g., maintenance windows).
Alerting on failures
- Monitor webhook delivery metrics:
  - High 4xx / 5xx rates from your side indicate handler issues.
  - Gaps in expected event volume may indicate upstream configuration changes.

Scheduling vs polling: why Monitor is preferable

You could simulate monitoring by polling Search every N minutes and diffing locally, but Monitor is designed to collapse that pipeline:

Single call to configure; infrastructure does the rest
- No need to build your own scheduler, crawler, or diff logic.
Evidence-based events, not raw pages
- You receive structured events with citations, not just “here’s a URL that changed.”
Predictable costs
- Monitor is billed per request at a known CPM.
- Polling via token-heavy browse/summarization tools makes spend unpredictable; small changes in page size or prompt behavior can blow up costs.
Consistency with other Parallel APIs
- Monitor uses the same AI-native index, live crawling, and Basis framework as Search, Task, Extract, and FindAll.
- This gives you consistent semantics and provenance across your entire agent stack.

Putting it all together: end-to-end architecture

A typical end-to-end deployment for scheduled monitoring with webhooks looks like this:

Configuration
- A backend service or internal console calls POST /monitor to register monitors with:
  - Objective, frequency, filters, webhook, metadata.
Execution
- Parallel executes monitors on schedule (hourly/daily/weekly).
- Each run uses the AI-native web index + live crawling to detect changes.
Event delivery
- For runs with changes, Parallel POSTs events to your webhook_url.
- Payload includes monitor/run identifiers, events, and Basis (citations/confidence/rationale).
Consumption
- Your webhook handler verifies signatures, deduplicates, and enqueues events.
- Downstream workers:
  - Apply confidence thresholds.
  - Optionally re-verify via Extract or Search.
  - Write into internal systems (tickets, data warehouse, vector DB, notification channels).
Governance
- Monitor metrics (event volume, false positives/negatives).
- Tune objectives, frequencies, and thresholds based on observed behavior.
- Use Basis fields to continuously validate and audit high-impact decisions.

If you’re ready to wire this into your stack, the fastest way to start is to prototype a single monitor in the playground, capture a webhook payload in a test endpoint, and then generalize that into a reusable monitoring service.

Get Started