Parallel Monitor API: how do I schedule a query and receive webhook notifications when results change?
RAG Retrieval & Web Search APIs

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

10 min read

Most teams reach for the Monitor API once they’ve already proven out Parallel Search or Task in an agent and now need “continuous awareness” instead of one-off calls. You want to schedule a query, have Parallel watch the web, and get webhook notifications only when something actually changes—without building your own crawl + diff + alert pipeline.

This guide walks through exactly that: how to create a monitor job, configure schedule and match logic, and receive webhook notifications when results change, using Parallel’s AI-native web index and Basis framework for evidence-backed alerts.

What the Monitor API does (and what it doesn’t)

Parallel Monitor turns the open web into a streaming signal for your agents:

  • You define what to watch using natural language or structured criteria.
  • Monitor runs on Parallel’s AI-native web index + live crawling at a configured cadence.
  • It emits new events (not full re-summaries) when something materially changes.
  • Each event carries citations, rationale, and confidence via Basis, so your system can decide what to trust or escalate.

It’s not a generic RSS replacement. Think of Monitor as a programmable “watcher” that uses the same retrieval and reasoning stack as Task/FindAll, but optimized for “only tell me when it matters”.

Core concepts

Before we schedule anything, it helps to align on the main objects and behaviors in the Monitor API.

Monitor job

A monitor job is the long-lived configuration that Parallel runs on a schedule:

  • objective or query: what you want Parallel to track.
  • scope: where to watch (e.g., entire web, domains, paths, result types).
  • processor_tier: how much compute you’re willing to allocate per run.
  • schedule: cron-like cadence or simple intervals.
  • webhook: where Parallel should POST events when something changes.
  • basis: whether to attach citations, explanations, and confidence.

You create a monitor once; Parallel handles the periodic work.

Monitor run

Each scheduled execution of a job is a run:

  • Uses your job’s config and Processor tier to search and/or crawl.
  • Compares outputs against prior runs.
  • Produces events for changes rather than re-sending the full state.

Runs are typically asynchronous; you don’t poll them in a tight loop. The point is to react to webhook pushes, not to re-poll.

Event

An event is what you actually care about: “something changed that matches this monitor.”

An event usually contains:

  • Summary / structured fields describing the change.
  • Diff or new entities depending on your monitor type.
  • Basis metadata:
    • citations: URLs and excerpts Parallel used.
    • reasoning: why it judged this as a change worth emitting.
    • confidence: calibrated likelihood the change is real and correctly interpreted.

Your webhook endpoint receives events as JSON payloads, and you decide—based on fields and confidence—whether to trigger downstream automation.

Step 1: Decide what you’re monitoring and at what cadence

Before touching the API, get clear on three dimensions:

  1. Objective

    • Example: “Monitor changes to OpenAI’s pricing page and API terms.”
    • Example: “Alert me when a new SEC 8-K filing appears for [company list].”
    • Example: “Track new case law on [specific issue] across major legal databases.”

  2. Freshness vs cost

    • High-frequency (e.g., every 5 minutes) → higher CPM but near-real-time.
    • Moderate (e.g., hourly or daily) → often sufficient for most product alerts.
    • Low-frequency (e.g., weekly) → good for slow-moving regulatory or policy changes.

  3. Depth per run

    • Lite/Base processors: shallow but fast and low cost.
    • Core/Pro: deeper research, cross-referenced sources.
    • Ultra/Ultra8x: maximum depth for highly specialized or high-risk scenarios.

Parallel’s Processor architecture lets you choose a tier per monitor so you’re not overpaying for simple checks.

Step 2: Create a webhook endpoint that can accept Parallel events

To receive notifications when results change, you need a web-accessible endpoint that:

  • Accepts POST requests (typically JSON).
  • Verifies the request (e.g., secret header or signed payload).
  • Validates and parses the event schema.
  • Returns a 2xx status quickly (you can do heavy work async).
  • Logs correlation IDs for debugging.

Minimal example (Node.js / Express)

import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.json());

const PARALLEL_WEBHOOK_SECRET = process.env.PARALLEL_WEBHOOK_SECRET || "";

// Basic HMAC verification example (adapt to actual signing scheme)
function verifySignature(req: express.Request): boolean {
  const signature = req.header("X-Parallel-Signature") || "";
  const payload = JSON.stringify(req.body);
  const hmac = crypto.createHmac("sha256", PARALLEL_WEBHOOK_SECRET);
  hmac.update(payload, "utf8");
  const expected = `sha256=${hmac.digest("hex")}`;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post("/webhooks/parallel-monitor", (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body;
  // Example fields — check actual Monitor event schema
  const { monitor_id, run_id, change_type, data, basis } = event;

  console.log("Monitor event received", { monitor_id, run_id, change_type });

  // Use Basis to programmatically filter
  if (basis?.confidence && basis.confidence < 0.7) {
    console.log("Low-confidence change, logging only.");
  } else {
    // Trigger downstream workflow, enqueue job, etc.
  }

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

app.listen(3000, () => {
  console.log("Webhook listening on port 3000");
});

You’ll plug this URL (e.g., https://yourapp.com/webhooks/parallel-monitor) into your Monitor job configuration.

Step 3: Define your Monitor configuration

Parallel Monitor is configured via the Platform UI or the API. For production agents and infrastructure, you’ll almost always use the API so everything lives in code.

The boundary conditions you define:

  • Query / objective: natural-language description of what to track.
  • Scope: constraints on where to look.
  • Processor tier: depth vs latency vs CPM.
  • Schedule: cron-like or simple interval.
  • Webhook: your endpoint + auth/secret.

Below is a representative JSON configuration for monitoring a pricing page and terms for a specific vendor.

{
  "name": "openai-pricing-terms-monitor",
  "objective": "Monitor changes to OpenAI's API pricing and terms of use.",
  "scope": {
    "domains": ["openai.com"],
    "paths": [
      "/pricing",
      "/policies/terms-of-use",
      "/policies/api-data-usage"
    ],
    "max_pages": 10
  },
  "processor": {
    "tier": "core",           
    "max_latency_seconds": 600
  },
  "schedule": {
    "type": "cron",
    "expression": "*/30 * * * *"  // every 30 minutes
  },
  "webhook": {
    "url": "https://yourapp.com/webhooks/parallel-monitor",
    "secret": "your_shared_secret",
    "headers": {
      "X-Custom-Source": "parallel-monitor"
    }
  },
  "basis": {
    "include_citations": true,
    "include_reasoning": true,
    "include_confidence": true
  },
  "change_detection": {
    "mode": "semantic_diff",
    "min_significance": 0.6
  }
}

Key pieces to notice:

  • change_detection.mode: "semantic_diff": Monitor focuses on meaningful content changes, not trivial HTML or layout updates.
  • min_significance: you can dial this up to reduce noise.
  • basis flags ensure your webhook events always include citations and confidence, letting you build evidence-based routing logic.

Step 4: Create a Monitor via the API

Assuming Parallel exposes Monitor over HTTPS in line with Search/Task/FindAll, a typical POST /monitor pattern looks like this.

Example: Creating a Monitor job (TypeScript / fetch)

const PARALLEL_API_KEY = process.env.PARALLEL_API_KEY || "";

async function createMonitor() {
  const body = {
    name: "openai-pricing-terms-monitor",
    objective: "Monitor changes to OpenAI's API pricing and terms of use.",
    scope: {
      domains: ["openai.com"],
      paths: [
        "/pricing",
        "/policies/terms-of-use",
        "/policies/api-data-usage"
      ],
      max_pages: 10
    },
    processor: {
      tier: "core",
      max_latency_seconds: 600
    },
    schedule: {
      type: "cron",
      expression: "*/30 * * * *"
    },
    webhook: {
      url: "https://yourapp.com/webhooks/parallel-monitor",
      secret: "your_shared_secret"
    },
    basis: {
      include_citations: true,
      include_reasoning: true,
      include_confidence: true
    },
    change_detection: {
      mode: "semantic_diff",
      min_significance: 0.6
    }
  };

  const res = await fetch("https://api.parallel.ai/monitor/v1/jobs", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${PARALLEL_API_KEY}`
    },
    body: JSON.stringify(body)
  });

  if (!res.ok) {
    const errorText = await res.text();
    throw new Error(`Failed to create monitor: ${res.status} ${errorText}`);
  }

  const json = await res.json();
  console.log("Monitor created:", JSON.stringify(json, null, 2));
  return json;
}

createMonitor()
  .catch(err => {
    console.error(err);
    process.exit(1);
  });

The response will typically include:

  • id — monitor job ID (store this).
  • status — e.g., active.
  • next_run_at — when the next scheduled run will execute.
  • created_at / updated_at.

You can update or pause monitors later via PATCH /monitor/v1/jobs/{id}.

Step 5: Understand the event schema you’ll receive

Once the monitor is active, Parallel will execute runs at your schedule and POST events to your webhook whenever a material change is detected.

A representative event payload might look like:

{
  "type": "monitor.event",
  "monitor_id": "mon_abc123",
  "run_id": "run_def456",
  "timestamp": "2026-04-12T10:22:01Z",
  "change_type": "content_update",
  "subject": {
    "url": "https://openai.com/pricing",
    "title": "API Pricing",
    "content_type": "html"
  },
  "diff": {
    "summary": "Price per 1M tokens for gpt-4o-mini increased from $0.15 to $0.18.",
    "before": {
      "price_per_1m_tokens": 0.15,
      "currency": "USD"
    },
    "after": {
      "price_per_1m_tokens": 0.18,
      "currency": "USD"
    }
  },
  "basis": {
    "confidence": 0.91,
    "citations": [
      {
        "url": "https://openai.com/pricing",
        "excerpt": "Input: $0.18 / 1M tokens"
      }
    ],
    "reasoning": "Compared the extracted pricing table across consecutive runs; detected a numeric increase in the gpt-4o-mini row."
  },
  "meta": {
    "processor_tier": "core",
    "run_duration_seconds": 47,
    "trace_id": "trace_xyz789"
  }
}

In your webhook handler, you can:

  • Filter by type and change_type.
  • Use basis.confidence to gate automation (e.g., only auto-update your billing calculator above 0.8).
  • Store diff data in your own store so your agent can reference historical changes without re-crawling.

Step 6: Programmatic decision-making using Basis

Parallel’s Basis framework is particularly important for Monitor because it lets you avoid brittle pattern matching on unstructured text.

Common patterns:

  1. Confidence thresholds
if (event.basis?.confidence && event.basis.confidence < 0.7) {
  // Log, but don’t trigger downstream changes automatically.
  return;
}
  1. Citation-based validation

If your environment is regulated or high-risk, you might:

  • Require at least one citation from an allowed domain.
  • Re-validate a subset of changes by re-running Extract or Search.
const citations = event.basis?.citations || [];
const onlyFromOpenAI = citations.every(c => c.url.includes("openai.com"));

if (!onlyFromOpenAI) {
  // Route to manual review queue or ignore.
}
  1. Rationale-aware alerts

You can incorporate basis.reasoning into alerts so incident responders see how Parallel concluded a change is meaningful, without re-running research.

Step 7: Monitoring at scale and keeping costs predictable

From an architecture standpoint, the main advantage of Parallel Monitor for web change detection is that you get per-request economics instead of a series of token-heavy browsing calls.

To keep Monitor cost predictable in production:

  • Right-size your Processor tier

    • Simple DOM or numeric diffs → lite or base.
    • Semantic policy / legal / technical docs → core or pro.
    • High-stakes, cross-site analysis (e.g., regulatory moves) → ultra.

  • Align schedule with business impact

    • Financial / security incidents → minutes.
    • Pricing / docs → 30–60 minutes.
    • Policy / TOS changes → daily.

  • Avoid combinatorial explosion

    • Use FindAll or Task to build a clean set of targets (e.g., all docs under /docs/* you actually care about).
    • Use Monitor to watch that curated set rather than crawling entire domains.

Because Monitor runs as discrete requests, you can model monthly CPM by:

CPM ≈ (monitors * runs_per_month_per_monitor) * cost_per_run_tier

This is materially easier to reason about than “browsing” flows where token volumes swing based on page length and summarization strategies.

Step 8: Example end-to-end flow

Putting all of this together, a production pattern looks like:

  1. Define monitors in your IaC or app code for:
    • Vendor pricing & limits
    • API docs and breaking changes
    • Relevant regulatory or policy sites
  2. Create monitors via API on deploy.
  3. Receive webhooks on /webhooks/parallel-monitor.
  4. Validate & filter events using:
    • Signature/header verification
    • basis.confidence thresholds
    • Domain constraints on citations
  5. Route events:
    • High-confidence, low-risk → auto-update config or data.
    • Medium-confidence or high-risk → human review queue.
    • Low-confidence → log and observe.
  6. Track performance:
    • Use trace_id (meta.trace_id) for debugging.
    • Monitor failure rates and run durations per monitor.

Methodology note: why Monitor is different from DIY crawlers

From the perspective of a retrieval and evaluation engineer, the critical difference between Parallel Monitor and a DIY “search + crawl + diff + alert” stack is:

  • Index + live crawling are AI-native
    • Monitor reuses the same AI-native web index and Processor architecture as Search/Task, tuned for token-dense compressed excerpts rather than human SERP snippets.
  • Change detection is semantic, not just textual
    • Differences are evaluated at the meaning level, reducing noise from presentation tweaks.
  • Evidence is first-class
    • Basis attaches citations, rationale, and confidence to every atomic change, enabling programmatic trust decisions.

This isn’t just more accurate—it’s easier to operate and debug. When something looks off, you can trace back each fact to its sources instead of treating the monitor as a black box.

Next step

If you’re ready to turn the open web into an event stream your agents can rely on—with verifiable, evidence-backed change notifications—start by wiring up a simple monitor and webhook in your staging environment.

Get Started

Back to RAG Retrieval & Web Search APIs

Keep Reading

More from RAG Retrieval & Web Search APIs

Parallel Chat API: how do I use the OpenAI-compatible streaming endpoint with web grounding and citations?

Read more

Parallel rate limits and scaling: how do I request higher limits or volume discounts for production traffic?

Read more

Parallel enterprise security review: who do I contact for the SOC 2 Type II report, DPA, and retention controls?

Read more