Monitor Migration Guide: Alpha to GA

This guide enumerates the contract differences between the Alpha Monitor API (/v1alpha/monitors) and the GA version (/v1/monitors), and outlines the steps required to migrate.

All ongoing development targets V1. The Alpha endpoints remain reachable but receive no new features:

Capabilities introduced after Alpha — snapshot monitors, structured output with basis, advanced_settings.location, and processor selection — are V1-only.
The Python and TypeScript SDKs expose typed bindings (client.monitor.*) only for V1. Alpha is reachable solely via the low-level HTTP client (client.post("/v1alpha/monitors", ...)).
The Parallel CLI targets V1 endpoints exclusively.

Highlights

Required type discriminant — "event_stream" (default Alpha behavior) or new "snapshot"; determines the settings shape. See Snapshot Quickstart.
Nested settings / advanced_settings — query, output_schema, include_backfill move under settings; source_policy and the new ISO 3166-1 location move under settings.advanced_settings. See Advanced Settings.
processor selection — Top-level "lite" (default) or "base". base increases recall and breadth for harder queries, at higher cost. See Monitor Quickstart.
Endpoint renames — Update → POST /{id}/update; Cancel → POST /{id}/cancel. New POST /{id}/trigger enqueues off-schedule one-off runs.
Unified events endpoint — GET /events supersedes both Alpha endpoints with cursor pagination and an optional event_group_id filter. See Events.
Restructured event payload — Stable event_id, event_type discriminator, and typed output with basis (citations, reasoning, confidence) replace the deprecated output string and the result object. See Events and Research Basis.
V1-only SDKs and CLI — Typed client.monitor.* bindings and the Parallel CLI target V1 exclusively.

Overview of Changes

Endpoints

Operation	Alpha	V1
Base path	`/v1alpha/monitors`	`/v1/monitors`
Create	`POST /v1alpha/monitors`	`POST /v1/monitors`
List (paginated)	`GET /v1alpha/monitors/list`	`GET /v1/monitors`; cursor-paginated; supports `type` and `status` query filters
Retrieve	`GET /v1alpha/monitors/{monitor_id}`	`GET /v1/monitors/{monitor_id}`
Update	`POST /v1alpha/monitors/{monitor_id}`	`POST /v1/monitors/{monitor_id}/update`
Cancel	`DELETE /v1alpha/monitors/{monitor_id}`	`POST /v1/monitors/{monitor_id}/cancel`
Trigger one-off run	—	`POST /v1/monitors/{monitor_id}/trigger`
List events	`GET /v1alpha/monitors/{monitor_id}/events?lookback_period=10d`	`GET /v1/monitors/{monitor_id}/events?cursor=&limit=&include_completions=`
Single execution events	`GET /v1alpha/monitors/{monitor_id}/event_groups/{event_group_id}`	`GET /v1/monitors/{monitor_id}/events?event_group_id=...`
Simulate event	`POST /v1alpha/monitors/{monitor_id}/simulate_event`	Removed; closest analogue is `POST /{monitor_id}/trigger`, which executes a real run rather than dispatching a synthetic event

Create Request

Concept	Alpha	V1
Monitor type	implicit; search-query monitors only	`type: "event_stream"` or `type: "snapshot"` (required)
Search query	top-level `query`	`settings.query` (event_stream only)
Output schema	top-level `output_schema`	`settings.output_schema` (event_stream only)
Backfill	top-level `include_backfill`	`settings.include_backfill` (event_stream only)
Source policy	top-level `source_policy`	`settings.advanced_settings.source_policy` (event_stream only)
Geo (`location`) (new)	—	`settings.advanced_settings.location` (ISO 3166-1 alpha-2, e.g. `"us"`, `"gb"`)
Snapshot baseline (new)	—	`settings.task_run_id` (snapshot only)
Processor (new)	—	top-level `processor: "lite" \| "base"` (defaults to `"lite"`)
Frequency	top-level `frequency` (`1h`–`30d`)	unchanged
Webhook	top-level `webhook`	unchanged
Metadata	top-level `metadata`	unchanged

Response

Field	Alpha	V1
`type`	—	new — `"event_stream"` or `"snapshot"`
`query`	top-level	now at `settings.query`
`output_schema`	top-level	now at `settings.output_schema`
`source_policy`	top-level	now at `settings.advanced_settings.source_policy`
`include_backfill`	top-level	now at `settings.include_backfill`
`cadence`	top-level (deprecated; `daily`/`weekly`/etc.)	removed; use `frequency`
`status`	`"active"` \| `"canceled"` (single-`l` spelling)	`"active"` \| `"cancelled"` (double-`l` spelling)
`last_run_at`	present	unchanged
`output` (snapshot only)	—	new; latest snapshot value for `type=snapshot` monitors

Events

V1 unifies the Alpha MonitorEventDetail shape into a single typed event with a stable event_id, a structured output object, and a basis array carrying per-field citations, reasoning, and confidence.

Field	Alpha	V1
Discriminator	`type: "event"`	`event_type: "event_stream" \| "snapshot"`
`event_id`	—	new; stable per-event identifier; safe for idempotent client-side dedup
`event_group_id`	present	unchanged
`event_date`	present	unchanged
`output` (string)	deprecated string field	removed
`result: { type, content }`	top-level (Text or JSON)	merged into `output: { type, content, basis }`
`source_urls`	top-level array	removed; URLs surface via `output.basis[].citations[].url`
`basis`	—	new; per-field citations, reasoning, and confidence (see Research Basis)

Webhook event types (monitor.event.detected, monitor.execution.completed, monitor.execution.failed) are unchanged. The webhook payload still wraps an event_group_id to be resolved against the events endpoint.

SDK and CLI Surface

V1 exposes typed bindings in both the Python and TypeScript SDKs and is the only version supported by the Parallel CLI. Alpha has no typed or CLI surface — it is reachable only via the low-level HTTP client.

Operation	Alpha (Python)	V1 (Python)
Create	`client.post("/v1alpha/monitors", body=...)`	`client.monitor.create(...)`
List	`client.get("/v1alpha/monitors/list", ...)`	`client.monitor.list(...)`
Retrieve	`client.get("/v1alpha/monitors/{id}", ...)`	`client.monitor.retrieve(monitor_id)`
Update	`client.post("/v1alpha/monitors/{id}", body=...)`	`client.monitor.update(monitor_id, ...)`
Cancel	`client.delete("/v1alpha/monitors/{id}", ...)`	`client.monitor.cancel(monitor_id)`
Trigger	—	`client.monitor.trigger(monitor_id)`
Events	`client.get("/v1alpha/monitors/{id}/events", ...)`	`client.monitor.events(monitor_id, ...)`

Migration Example

Before (Alpha)

curl https://api.parallel.ai/v1alpha/monitors \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "query": "AI startup funding announcements",
    "frequency": "1d",
    "include_backfill": false,
    "source_policy": {
      "include_domains": ["techcrunch.com", "bloomberg.com"]
    },
    "webhook": {
      "url": "https://example.com/webhook",
      "event_types": ["monitor.event.detected"]
    },
    "metadata": { "external_id": "acme-monitor-001" }
  }'

import os
from httpx import Response
from parallel import Parallel

client = Parallel(api_key=os.environ["PARALLEL_API_KEY"])

monitor = client.post(
    "/v1alpha/monitors",
    cast_to=Response,
    body={
        "query": "AI startup funding announcements",
        "frequency": "1d",
        "include_backfill": False,
        "source_policy": {
            "include_domains": ["techcrunch.com", "bloomberg.com"],
        },
        "webhook": {
            "url": "https://example.com/webhook",
            "event_types": ["monitor.event.detected"],
        },
        "metadata": {"external_id": "acme-monitor-001"},
    },
).json()

print(f"Monitor ID: {monitor['monitor_id']}")

import Parallel from "parallel-web";

const client = new Parallel({ apiKey: process.env.PARALLEL_API_KEY });

const monitor = (await client.post("/v1alpha/monitors", {
  body: {
    query: "AI startup funding announcements",
    frequency: "1d",
    include_backfill: false,
    source_policy: {
      include_domains: ["techcrunch.com", "bloomberg.com"],
    },
    webhook: {
      url: "https://example.com/webhook",
      event_types: ["monitor.event.detected"],
    },
    metadata: { external_id: "acme-monitor-001" },
  },
})) as { monitor_id: string; status: string };

console.log(`Monitor ID: ${monitor.monitor_id}`);

After (V1)

curl https://api.parallel.ai/v1/monitors \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "type": "event_stream",
    "frequency": "1d",
    "processor": "lite",
    "settings": {
      "query": "AI startup funding announcements",
      "include_backfill": false,
      "advanced_settings": {
        "source_policy": {
          "include_domains": ["techcrunch.com", "bloomberg.com"]
        },
        "location": "us"
      }
    },
    "webhook": {
      "url": "https://example.com/webhook",
      "event_types": ["monitor.event.detected"]
    },
    "metadata": { "external_id": "acme-monitor-001" }
  }'

import os
from parallel import Parallel

client = Parallel(api_key=os.environ["PARALLEL_API_KEY"])

monitor = client.monitor.create(
    type="event_stream",
    frequency="1d",
    processor="lite",
    settings={
        "query": "AI startup funding announcements",
        "include_backfill": False,
        "advanced_settings": {
            "source_policy": {
                "include_domains": ["techcrunch.com", "bloomberg.com"],
            },
            "location": "us",
        },
    },
    webhook={
        "url": "https://example.com/webhook",
        "event_types": ["monitor.event.detected"],
    },
    metadata={"external_id": "acme-monitor-001"},
)

print(f"Monitor ID: {monitor.monitor_id}")

import Parallel from "parallel-web";

const client = new Parallel({ apiKey: process.env.PARALLEL_API_KEY });

const monitor = await client.monitor.create({
  type: "event_stream",
  frequency: "1d",
  processor: "lite",
  settings: {
    query: "AI startup funding announcements",
    include_backfill: false,
    advanced_settings: {
      source_policy: {
        include_domains: ["techcrunch.com", "bloomberg.com"],
      },
      location: "us",
    },
  },
  webhook: {
    url: "https://example.com/webhook",
    event_types: ["monitor.event.detected"],
  },
  metadata: { external_id: "acme-monitor-001" },
});

console.log(`Monitor ID: ${monitor.monitor_id}`);

Migration Checklist

Required changes

Update the base path from /v1alpha/monitors to /v1/monitors.
Add the type discriminant ("event_stream" or "snapshot") to every CreateMonitorRequest.
Move query, output_schema, and include_backfill from top-level into settings.
Move source_policy from top-level into settings.advanced_settings.source_policy.
Migrate Update calls from POST /{id} to POST /{id}/update.
Migrate Cancel calls from DELETE /{id} to POST /{id}/cancel.
Replace GET /{id}/event_groups/{event_group_id} with GET /{id}/events?event_group_id=....
Replace the lookback_period query parameter with cursor-based pagination (cursor, limit).
Update the status enum check from "canceled" to "cancelled" (double l).
Replace reads of result.content and source_urls with output.content and output.basis[].citations[].url.
Drop the deprecated top-level string output field on event records.

Optional enhancements

Set processor: "base" for harder queries that need higher recall and breadth.
Set settings.advanced_settings.location to scope retrieval to a single country.
Replace low-level client.post(...) calls with client.monitor.* SDK bindings.
Use event_id for idempotent client-side dedup across pagination and webhook retries.
Consume output.basis for per-field citations, reasoning, and confidence.
Issue POST /{id}/trigger for off-schedule one-off executions.
Pass include_completions=true to enumerate executions that produced no events (useful for audit traces).
Adopt type=snapshot for field-level diffing of structured Task Run outputs (see Snapshot Quickstart).

Additional Resources

Monitor Quickstart — V1 monitor lifecycle and webhook walkthrough
Snapshot Quickstart — type=snapshot walkthrough
Events — V1 event schemas and retrieval semantics
Webhooks — payload schemas and HMAC verification
V1 API Reference — generated from public-openapi.json
Legacy Alpha API Reference — /v1alpha/monitors endpoint reference

Questions? Contact support@parallel.ai.

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

Monitor Migration Guide: Alpha to GA

Highlights

Overview of Changes

Endpoints

Create Request

Response

Events

SDK and CLI Surface

Migration Example

Before (Alpha)

After (V1)

Migration Checklist

Required changes

Optional enhancements

Additional Resources

​Highlights

​Overview of Changes

​Endpoints

​Create Request

​Response

​Events

​SDK and CLI Surface

​Migration Example

​Before (Alpha)

​After (V1)

​Migration Checklist

​Required changes

​Optional enhancements

​Additional Resources

Highlights

Overview of Changes

Endpoints

Create Request

Response

Events

SDK and CLI Surface

Migration Example

Before (Alpha)

After (V1)

Migration Checklist

Required changes

Optional enhancements

Additional Resources