Monitor Migration Guide: Alpha to GA

​

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

​

Create Request

​

Response

​

Events

​

SDK and CLI Surface

​

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" }
  }'

​

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" }
  }'

​

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