openapi: 3.1.0 info: title: Parallel Chat API (Beta) Chat API (Beta) Monitor API description: Parallel API contact: name: Parallel Support url: https://parallel.ai email: support@parallel.ai version: 0.1.2 servers: - url: https://api.parallel.ai description: Parallel API security: - ApiKeyAuth: [] tags: - name: Monitor description: 'The Monitor API watches the web for material changes on a fixed frequency. Each monitor runs once on creation and then on its configured schedule, emitting events when meaningful changes are detected. - `event_stream` monitors track a search query and emit an event for each new material change. - `snapshot` monitors track a specific task run''s output and emit an event when the output changes. Results can be polled via the events endpoint or delivered via webhooks.' paths: /v1/monitors: post: tags: - Monitor summary: Create Monitor description: 'Create a monitor. Monitors run on a fixed frequency to detect material changes in web content. Set `type=event_stream` to monitor a search query, or `type=snapshot` to monitor a specific task run''s output. The monitor runs once immediately at creation, then continues on the configured schedule.' operationId: create_monitor_v1_monitors_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMonitorRequest' responses: '201': description: Monitor created successfully. content: application/json: schema: $ref: '#/components/schemas/MonitorResponse' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'Unprocessable content: request validation error' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unprocessable content: request validation error' schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\nmonitor = client.monitor.create(\n type=\"event_stream\",\n frequency=\"1d\",\n settings={\"query\": \"Extract recent news about AI\"},\n)\nprint(monitor.monitor_id)" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst monitor = await client.monitor.create({\n type: 'event_stream',\n frequency: '1d',\n settings: { query: 'Extract recent news about AI' },\n});\nconsole.log(monitor.monitor_id);" get: tags: - Monitor summary: List Monitors description: 'List monitors ordered by creation time, newest first. Monitors are sorted by `created_at` descending. `limit` defaults to 100. Use `next_cursor` from the response and pass it as `cursor` to fetch the next page. Pagination ends when `next_cursor` is absent. By default only `active` monitors are returned. Pass `status=cancelled` or both values to include cancelled monitors. The legacy Monitor API (`/v1alpha/monitors` endpoints) is documented under the `Monitor (Alpha)` tag.' operationId: list_monitors_v1_monitors_get parameters: - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Pagination token from `next_cursor` in a previous response. Omit to start from the most recently created monitor. title: Cursor description: Pagination token from `next_cursor` in a previous response. Omit to start from the most recently created monitor. - name: limit in: query required: false schema: anyOf: - type: integer maximum: 10000 minimum: 1 - type: 'null' description: Maximum number of monitors to return. Defaults to 100. Between 1 and 10000. title: Limit description: Maximum number of monitors to return. Defaults to 100. Between 1 and 10000. - name: type in: query required: false schema: anyOf: - type: array items: enum: - event_stream - snapshot type: string - type: 'null' description: Filter by monitor type. Pass multiple times to filter by multiple values. Omit to return all types. title: Type description: Filter by monitor type. Pass multiple times to filter by multiple values. Omit to return all types. - name: status in: query required: false schema: anyOf: - type: array items: enum: - active - cancelled type: string - type: 'null' description: Filter by monitor status. Pass multiple times to filter by multiple values. Defaults to `active` only. title: Status description: Filter by monitor status. Pass multiple times to filter by multiple values. Defaults to `active` only. responses: '200': description: Paginated list of monitors. content: application/json: schema: $ref: '#/components/schemas/PaginatedMonitorResponse' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\npage = client.monitor.list(limit=10)\nfor monitor in page.monitors:\n print(monitor.monitor_id, monitor.status)" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst page = await client.monitor.list({ limit: 10 });\nfor (const monitor of page.monitors) {\n console.log(monitor.monitor_id, monitor.status);\n}" /v1/monitors/{monitor_id}: get: tags: - Monitor summary: Retrieve Monitor description: 'Retrieve a monitor. Retrieves a specific monitor by `monitor_id`. Returns the monitor configuration including status, frequency, query, and webhook settings.' operationId: retrieve_monitor_v1_monitors__monitor_id__get parameters: - name: monitor_id in: path required: true schema: type: string title: Monitor Id responses: '200': description: Monitor retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/MonitorResponse' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Monitor not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Monitor not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-code-samples: - lang: Python source: 'from parallel import Parallel client = Parallel() monitor = client.monitor.retrieve("monitor_id") print(monitor.status)' - lang: TypeScript source: 'import Parallel from "parallel-web"; const client = new Parallel(); const monitor = await client.monitor.retrieve(''monitor_id''); console.log(monitor.status);' /v1/monitors/{monitor_id}/cancel: post: tags: - Monitor summary: Cancel Monitor description: 'Cancel a monitor. Permanently stops the monitor from running. Cancellation is irreversible — create a new monitor to resume monitoring. Cancelling an already-cancelled monitor is a no-op.' operationId: cancel_monitor_v1_monitors__monitor_id__cancel_post parameters: - name: monitor_id in: path required: true schema: type: string title: Monitor Id responses: '200': description: Monitor cancelled successfully. content: application/json: schema: $ref: '#/components/schemas/MonitorResponse' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Monitor not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Monitor not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'Unprocessable content: request validation error' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unprocessable content: request validation error' schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: 'from parallel import Parallel client = Parallel() monitor = client.monitor.cancel("monitor_id") print(monitor.status)' - lang: TypeScript source: 'import Parallel from "parallel-web"; const client = new Parallel(); const monitor = await client.monitor.cancel(''monitor_id''); console.log(monitor.status);' /v1/monitors/{monitor_id}/events: get: tags: - Monitor summary: List Monitor Events description: 'List events for a monitor, newest first. Pass `event_group_id` to narrow results to a single execution. Otherwise returns all executions newest-first; use `next_cursor` to paginate. Set `include_completions=true` to also include no-change executions.' operationId: list_monitor_events_v1_monitors__monitor_id__events_get parameters: - name: monitor_id in: path required: true schema: type: string title: Monitor Id - name: event_group_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter to a single execution. Values come from `event_group_id` in webhook events and listed events. Pagination params are ignored when set. title: Event Group Id description: Filter to a single execution. Values come from `event_group_id` in webhook events and listed events. Pagination params are ignored when set. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Pass `next_cursor` from a previous response to retrieve more events. title: Cursor description: Pass `next_cursor` from a previous response to retrieve more events. - name: limit in: query required: false schema: anyOf: - type: integer maximum: 100 minimum: 1 - type: 'null' description: Maximum number of events to return. Defaults to 20. Between 1 and 100. title: Limit description: Maximum number of events to return. Defaults to 20. Between 1 and 100. - name: include_completions in: query required: false schema: type: boolean description: When true, include completion events for executions that ran but detected no material changes. Useful for auditing execution history. default: false title: Include Completions description: When true, include completion events for executions that ran but detected no material changes. Useful for auditing execution history. responses: '200': description: Monitor events retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/PaginatedMonitorEvents' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Monitor not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Monitor not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'Unprocessable content: invalid cursor or request validation error' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unprocessable content: invalid cursor or request validation error' schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\npage = client.monitor.events(\"monitor_id\", limit=20)\nfor event in page.events:\n print(event)" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst page = await client.monitor.events('monitor_id', { limit: 20 });\nfor (const event of page.events) {\n console.log(event);\n}" /v1/monitors/{monitor_id}/trigger: post: tags: - Monitor summary: Trigger Monitor Run description: 'Trigger an immediate monitor run. Enqueues a one-off execution of the monitor outside its normal schedule. The monitor''s regular schedule is not affected. An event is only emitted if the execution detects a material change. Cancelled monitors cannot be triggered.' operationId: trigger_monitor_run_v1_monitors__monitor_id__trigger_post parameters: - name: monitor_id in: path required: true schema: type: string title: Monitor Id responses: '204': description: Monitor run enqueued. '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Monitor not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Monitor not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'Unprocessable content: request validation error' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unprocessable content: request validation error' schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: 'from parallel import Parallel client = Parallel() client.monitor.trigger("monitor_id")' - lang: TypeScript source: 'import Parallel from "parallel-web"; const client = new Parallel(); await client.monitor.trigger(''monitor_id'');' /v1/monitors/{monitor_id}/update: post: tags: - Monitor summary: Update Monitor description: 'Update a monitor. Only fields explicitly included in the request body are changed. Pass `null` for `webhook` or `metadata` to clear those fields. Pass `type` and `settings` to update type-specific settings on an `event_stream` monitor. At least one field must be provided. Cancelled monitors cannot be updated.' operationId: update_monitor_v1_monitors__monitor_id__update_post parameters: - name: monitor_id in: path required: true schema: type: string title: Monitor Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMonitorRequest' responses: '200': description: Monitor updated successfully. content: application/json: schema: $ref: '#/components/schemas/MonitorResponse' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Monitor not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Monitor not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'Unprocessable content: request validation error' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unprocessable content: request validation error' schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\nmonitor = client.monitor.update(\n \"monitor_id\",\n frequency=\"12h\",\n type=\"event_stream\",\n settings={\"query\": \"Extract recent funding news about AI startups\"},\n)\nprint(monitor.frequency)" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst monitor = await client.monitor.update('monitor_id', {\n frequency: '12h',\n type: 'event_stream',\n settings: { query: 'Extract recent funding news about AI startups' },\n});\nconsole.log(monitor.frequency);" components: schemas: MonitorCompletionEvent: properties: event_type: type: string enum: - completion const: completion title: Event Type description: Discriminant for the completion event variant. default: completion timestamp: type: string format: date-time title: Timestamp description: Timestamp of when the monitor execution completed, as an RFC 3339 string. examples: - '2025-01-15T10:30:00Z' type: object required: - timestamp title: MonitorCompletionEvent description: 'Emitted when a monitor execution ran but detected no material changes. Only returned when `include_completions=true` is passed to the list events endpoint. Useful for auditing execution history alongside content events.' PaginatedMonitorEvents: properties: events: items: oneOf: - $ref: '#/components/schemas/MonitorEventStreamEvent' - $ref: '#/components/schemas/MonitorSnapshotEvent' - $ref: '#/components/schemas/MonitorCompletionEvent' - $ref: '#/components/schemas/MonitorErrorEvent' discriminator: propertyName: event_type mapping: completion: '#/components/schemas/MonitorCompletionEvent' error: '#/components/schemas/MonitorErrorEvent' event_stream: '#/components/schemas/MonitorEventStreamEvent' snapshot: '#/components/schemas/MonitorSnapshotEvent' type: array title: Events description: Monitor events returned by this request, ordered newest first. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Pass as `cursor` to retrieve more events. Absent when there are no more events. warnings: anyOf: - items: $ref: '#/components/schemas/Warning' type: array - type: 'null' title: Warnings description: Execution caveats for this page of events, e.g. compute limits. type: object required: - events title: PaginatedMonitorEvents description: Paginated list of monitor events, newest first. PaginatedMonitorResponse: properties: monitors: items: $ref: '#/components/schemas/MonitorResponse' type: array title: Monitors description: List of monitors for the current page. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque pagination token. Pass as `cursor` to retrieve the next page. Absent when there are no more pages. type: object required: - monitors title: PaginatedMonitorResponse description: Paginated list of monitors. MonitorSnapshotOutput: properties: latest_snapshot: anyOf: - oneOf: - $ref: '#/components/schemas/TaskRunTextOutput' - $ref: '#/components/schemas/TaskRunJsonOutput' discriminator: propertyName: type mapping: json: '#/components/schemas/TaskRunJsonOutput' text: '#/components/schemas/TaskRunTextOutput' - type: 'null' title: Latest Snapshot description: Task run output from the most recent completed execution of this snapshot monitor — same structure as the output of the original task run the monitor was created from. `null` until the first run completes. type: object title: MonitorSnapshotOutput description: Runtime output state for a `snapshot` monitor. MonitorWebhook: properties: url: type: string title: Url description: URL for the webhook. examples: - https://example.com/webhook event_types: items: type: string enum: - monitor.event.detected - monitor.execution.completed - monitor.execution.failed type: array title: Event Types description: Event types to send the webhook notifications for. type: object required: - url title: MonitorWebhook description: Webhook configuration for a monitor. MonitorEventStreamResponseSettings: properties: query: type: string title: Query description: The search query being monitored. examples: - Extract recent news about AI output_schema: anyOf: - $ref: '#/components/schemas/JsonSchema' - type: 'null' description: JSON schema that constrains and structures the event output. When set, events are returned as JSON objects matching this schema. include_backfill: anyOf: - type: boolean - type: 'null' title: Include Backfill description: If true, the first execution returns a sample of recent historical events matching the query (preview only — not exhaustive). If false or omitted, only events from the monitor's creation date onward are returned. Subsequent executions are always incremental. advanced_settings: anyOf: - $ref: '#/components/schemas/AdvancedMonitorSettings' - type: 'null' description: Advanced monitor configuration. type: object required: - query title: MonitorEventStreamResponseSettings description: Type-specific response fields for an `event_stream` monitor. CreateMonitorRequest: properties: type: type: string enum: - event_stream - snapshot title: Type description: Type of monitor to create. `event_stream` monitors a search query for material changes; `snapshot` monitors a specific task run's output. Determines the expected shape of `settings`. examples: - event_stream - snapshot frequency: type: string title: Frequency description: 'Frequency of the monitor. Format: '''' where unit is ''h'' (hours), ''d'' (days), or ''w'' (weeks). Must be between 1h and 30d (inclusive).' examples: - 1h - 12h - 1d - 7d - 30d processor: type: string enum: - lite - base title: Processor description: Processor to use for the monitor. `lite` is faster and cheaper; `base` performs more thorough analysis at higher cost and latency. Defaults to `lite`. default: lite webhook: anyOf: - $ref: '#/components/schemas/MonitorWebhook' - type: 'null' description: Webhook to receive notifications about the monitor's execution. metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: 'User-provided metadata stored with the monitor and echoed back in webhook notifications and GET responses, so you can map events to objects in your application. Keys: max 16 chars; values: max 512 chars.' examples: - slack_thread_id: '1234567890.123456' user_id: U123ABC settings: anyOf: - $ref: '#/components/schemas/MonitorEventStreamSettings' - $ref: '#/components/schemas/MonitorSnapshotSettings' title: Settings description: 'Type-specific settings for the monitor. The expected shape is determined by the root `type` field: pass `MonitorEventStreamSettings` when `type` is `event_stream`, and `MonitorSnapshotSettings` when `type` is `snapshot`.' type: object required: - type - frequency - settings title: CreateMonitorRequest description: 'Request body to create a monitor. The `type` field at the root determines the expected shape of `settings`: `event_stream` requires `MonitorEventStreamSettings`, and `snapshot` requires `MonitorSnapshotSettings`.' MonitorSnapshotEvent: properties: event_id: type: string title: Event Id description: Stable identifier for this event. Safe to use for client-side deduplication across pagination and retries. event_group_id: type: string title: Event Group Id description: ID of the event group that owns this event. event_date: anyOf: - type: string - type: 'null' title: Event Date description: Date when this event was produced. ISO 8601 date (YYYY-MM-DD) or partial (YYYY-MM or YYYY). examples: - '2026-04-07' event_type: type: string enum: - snapshot const: snapshot title: Event Type description: Discriminant for the snapshot event variant. default: snapshot changed_output: oneOf: - $ref: '#/components/schemas/TaskRunTextOutput' - $ref: '#/components/schemas/TaskRunJsonOutput' title: Changed Output description: Partial output containing only the fields that changed since the previous execution, each with its `basis` (reasoning and citations). discriminator: propertyName: type mapping: json: '#/components/schemas/TaskRunJsonOutput' text: '#/components/schemas/TaskRunTextOutput' previous_output: oneOf: - $ref: '#/components/schemas/TaskRunTextOutput' - $ref: '#/components/schemas/TaskRunJsonOutput' title: Previous Output description: The full output from the prior run, including all fields and basis. discriminator: propertyName: type mapping: json: '#/components/schemas/TaskRunJsonOutput' text: '#/components/schemas/TaskRunTextOutput' type: object required: - event_id - event_group_id - event_date - changed_output - previous_output title: MonitorSnapshotEvent description: 'Snapshot diff event emitted when a monitored task run''s output changes. `changed_output` contains only the fields that changed since the previous execution, along with their `basis` (reasoning + citations). `previous_output` holds the complete output from the prior run for comparison.' HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TaskRunTextOutput: properties: basis: items: $ref: '#/components/schemas/FieldBasis' type: array title: Basis description: Basis for the output. The basis has a single field 'output'. type: type: string const: text title: Type description: The type of output being returned, as determined by the output schema of the task spec. mcp_tool_calls: anyOf: - items: $ref: '#/components/schemas/McpToolCall' type: array - type: 'null' title: Mcp Tool Calls description: MCP tool calls made by the task. beta_fields: anyOf: - additionalProperties: true type: object - type: 'null' title: Beta Fields description: Deprecated. mcp-server-2025-07-17 is now included directly in the output (e.g. mcp_tool_calls). deprecated: true content: type: string title: Content description: Text output from the task. type: object required: - basis - type - content title: TaskRunTextOutput description: Output from a task that returns text. MonitorSnapshotResponseSettings: properties: task_run_id: type: string title: Task Run Id description: ID of the task run used as the monitoring baseline. query: type: string title: Query description: The original task input from the baseline task run that this monitor tracks. examples: - Extract recent news about AI output_schema: anyOf: - $ref: '#/components/schemas/JsonSchema' - type: 'null' description: JSON schema derived from the baseline task run that constrains and structures the event output. type: object required: - task_run_id - query title: MonitorSnapshotResponseSettings description: Configuration settings for a `snapshot` monitor. UpdateMonitorEventStreamSettings: properties: query: anyOf: - type: string - type: 'null' title: Query description: Updated search query for the monitor. Use this for minor updates to prompts and instructions only. Major changes to the query may lead to unexpected results in change detection, as the monitor compares new results with what was previously seen. examples: - Extract recent news about AI advanced_settings: anyOf: - $ref: '#/components/schemas/AdvancedMonitorSettings' - type: 'null' description: Advanced monitor configuration. type: object title: UpdateMonitorEventStreamSettings description: Type-specific update settings for an `event_stream` monitor. MonitorSnapshotSettings: properties: task_run_id: type: string title: Task Run Id description: Task run ID whose output becomes the data and schema for the monitor. type: object required: - task_run_id title: MonitorSnapshotSettings description: Type-specific settings for a `snapshot` monitor. MonitorResponse: properties: type: type: string enum: - event_stream - snapshot title: Type description: The type of monitor. examples: - event_stream - snapshot monitor_id: type: string title: Monitor ID description: ID of the monitor. status: type: string enum: - active - cancelled title: Status description: Status of the monitor. examples: - active - cancelled frequency: type: string title: Frequency description: 'Frequency of the monitor. Format: '''' where unit is ''h'' (hours), ''d'' (days), or ''w'' (weeks). Must be between 1h and 30d (inclusive).' examples: - 1h - 12h - 1d - 7d - 30d processor: type: string enum: - lite - base title: Processor description: Processor to use for the monitor. `lite` is faster and cheaper; `base` performs more thorough analysis at higher cost and latency. Defaults to `lite`. examples: - lite - base webhook: anyOf: - $ref: '#/components/schemas/MonitorWebhook' - type: 'null' description: Webhook configuration for the monitor. metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: 'User-provided metadata stored with the monitor and echoed back in webhook notifications and GET responses, so you can map events to objects in your application. Keys: max 16 chars; values: max 512 chars.' examples: - slack_thread_id: '1234567890.123456' user_id: U123ABC created_at: type: string format: date-time title: Created At description: Timestamp of the creation of the monitor, as an RFC 3339 string. examples: - '2025-01-15T10:30:00Z' last_run_at: anyOf: - type: string - type: 'null' title: Last Run At description: Timestamp of the last run for the monitor, as an RFC 3339 string. examples: - '2025-01-15T10:30:00Z' settings: anyOf: - $ref: '#/components/schemas/MonitorEventStreamResponseSettings' - $ref: '#/components/schemas/MonitorSnapshotResponseSettings' title: Settings description: 'Type-specific configuration. Shape is determined by `type`: `MonitorEventStreamResponseSettings` for `event_stream`, `MonitorSnapshotResponseSettings` for `snapshot`.' output: anyOf: - $ref: '#/components/schemas/MonitorSnapshotOutput' - type: 'null' description: Runtime output state. Present only for `snapshot` monitors; `null` for `event_stream` monitors. type: object required: - type - monitor_id - status - frequency - processor - created_at - settings title: MonitorResponse description: 'Response object for a monitor. The `type` field at the root determines the concrete shape of `settings`: `event_stream` uses `MonitorEventStreamResponseSettings`, and `snapshot` uses `MonitorSnapshotResponseSettings`. Snapshot monitors also carry an `output` field (`MonitorSnapshotOutput`) with the latest computed state.' MonitorEventStreamSettings: properties: query: type: string title: Query description: Search query to monitor for material changes. examples: - Extract recent news about AI output_schema: anyOf: - $ref: '#/components/schemas/JsonSchema' - type: 'null' description: JSON schema that constrains and structures the event output. When set, events are returned as JSON objects matching this schema instead of free-form text. include_backfill: anyOf: - type: boolean - type: 'null' title: Include Backfill description: If true, the first execution returns a sample of recent historical events matching the query (preview only — not exhaustive). If false or omitted, only events from the monitor's creation date onward are returned. Subsequent executions are always incremental. advanced_settings: anyOf: - $ref: '#/components/schemas/AdvancedMonitorSettings' - type: 'null' description: Advanced monitor configuration. type: object required: - query title: MonitorEventStreamSettings description: Type-specific settings for an `event_stream` monitor. AdvancedMonitorSettings: properties: source_policy: anyOf: - $ref: '#/components/schemas/SourcePolicy' - type: 'null' description: 'Domain filtering preferences: preferred and disallowed domains for monitor search results.' examples: - exclude_domains: - reddit.com - x.com - .ai include_domains: - wikipedia.org - usa.gov - .edu location: anyOf: - type: string - type: 'null' title: Location description: ISO 3166-1 alpha-2 country code for geo-targeted monitor results. examples: - us - gb - de - jp type: object title: AdvancedMonitorSettings description: Advanced monitor configuration. UpdateMonitorRequest: properties: type: anyOf: - type: string enum: - event_stream - snapshot - type: 'null' title: Type description: Type of the monitor being updated. Required when `settings` is provided; must be `event_stream` (snapshot monitors have no updatable type-specific settings). examples: - event_stream frequency: anyOf: - type: string - type: 'null' title: Frequency description: 'Frequency of the monitor. Format: '''' where unit is ''h'' (hours), ''d'' (days), or ''w'' (weeks). Must be between 1h and 30d (inclusive).' examples: - 1h - 12h - 1d - 7d - 30d webhook: anyOf: - $ref: '#/components/schemas/MonitorWebhook' - type: 'null' description: Webhook to receive notifications about the monitor's execution. metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: 'User-provided metadata stored with the monitor and echoed back in webhook notifications and GET responses, so you can map events to objects in your application. Keys: max 16 chars; values: max 512 chars.' examples: - slack_thread_id: '1234567890.123456' user_id: U123ABC settings: anyOf: - $ref: '#/components/schemas/UpdateMonitorEventStreamSettings' - type: 'null' description: Type-specific settings to update. Only valid when `type` is `event_stream`. Pass `settings.query` to update the prompt, or `null` for `settings.advanced_settings` to clear it. type: object title: UpdateMonitorRequest description: 'Request body to update a monitor. Only fields that are explicitly included in the request body are updated. Pass `null` for `webhook` or `metadata` to clear those fields. To update type-specific settings on an `event_stream` monitor, include `type` and `settings`; pass `settings.query` to update the prompt, or `null` for `settings.advanced_settings` to clear it. If `settings` is provided, `type` is required to identify the settings shape. The request must still include at least one field to update; empty updates fail validation.' FieldBasis: description: Citations and reasoning supporting one field of a task output. properties: field: description: Name of the output field. title: Field type: string citations: default: [] description: List of citations supporting the output field. items: $ref: '#/components/schemas/Citation' title: Citations type: array reasoning: description: Reasoning for the output field. title: Reasoning type: string confidence: anyOf: - type: string - type: 'null' default: null description: Confidence level for the output field. Only certain processors provide confidence levels. examples: - low - medium - high title: Confidence required: - field - reasoning title: FieldBasis type: object Error: properties: ref_id: type: string title: Reference ID description: Reference ID for the error. message: type: string title: Message description: Human-readable message. detail: anyOf: - additionalProperties: true type: object - type: 'null' title: Detail description: Optional detail supporting the error. type: object required: - ref_id - message title: Error description: An error message. MonitorErrorEvent: properties: event_type: type: string enum: - error const: error title: Event Type description: Discriminant for the error event variant. default: error error_message: type: string title: Error Message description: Human-readable description of the failure. timestamp: type: string format: date-time title: Timestamp description: Timestamp of when the monitor execution failed, as an RFC 3339 string. examples: - '2025-01-15T10:30:00Z' type: object required: - error_message - timestamp title: MonitorErrorEvent description: 'Emitted when a monitor execution failed (e.g. payment or quota error). Always included in the events list regardless of `include_completions`.' Citation: description: A citation for a task output. properties: title: anyOf: - type: string - type: 'null' default: null description: Title of the citation. title: Title url: description: URL of the citation. title: Url type: string excerpts: anyOf: - items: type: string type: array - type: 'null' default: null description: Excerpts from the citation supporting the output. Only certain processors provide excerpts. title: Excerpts required: - url title: Citation type: object ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError Warning: properties: type: type: string enum: - spec_validation_warning - input_validation_warning - warning title: Type description: Type of warning. Note that adding new warning types is considered a backward-compatible change. examples: - spec_validation_warning - input_validation_warning message: type: string title: Message description: Human-readable message. detail: anyOf: - additionalProperties: true type: object - type: 'null' title: Detail description: Optional detail supporting the warning. type: object required: - type - message title: Warning description: Human-readable message for a task. ErrorResponse: properties: type: type: string const: error title: Type description: Always 'error'. error: $ref: '#/components/schemas/Error' description: Error. type: object required: - type - error title: ErrorResponse description: Response object used for non-200 status codes. SourcePolicy: properties: include_domains: items: type: string type: array title: Include Domains description: List of domains to restrict the results to. If specified, only sources from these domains will be included. Accepts plain domains (e.g., example.com, subdomain.example.gov) or bare domain extension starting with a period (e.g., .gov, .edu, .co.uk). The combined number of domains in include_domains and exclude_domains cannot exceed 200. examples: - - wikipedia.org - usa.gov - .edu exclude_domains: items: type: string type: array title: Exclude Domains description: List of domains to exclude from results. If specified, sources from these domains will be excluded. Accepts plain domains (e.g., example.com, subdomain.example.gov) or bare domain extension starting with a period (e.g., .gov, .edu, .co.uk). The combined number of domains in include_domains and exclude_domains cannot exceed 200. examples: - - reddit.com - x.com - .ai after_date: anyOf: - type: string format: date - type: 'null' title: After Date description: Optional start date for filtering search results. Results will be limited to content published on or after this date. Provided as an RFC 3339 date string (YYYY-MM-DD). examples: - '2024-01-01' type: object title: SourcePolicy description: 'Source policy for web search results. This policy governs which sources are allowed/disallowed in results.' JsonSchema: properties: json_schema: additionalProperties: true type: object title: Json Schema description: A JSON Schema object. Only a subset of JSON Schema is supported. examples: - additionalProperties: false properties: gdp: description: GDP in USD for the year, formatted like '$3.1 trillion (2023)' type: string required: - gdp type: object type: type: string const: json title: Type description: The type of schema being defined. Always `json`. default: json type: object required: - json_schema title: JsonSchema description: JSON schema for a task input or output. TaskRunJsonOutput: properties: basis: items: $ref: '#/components/schemas/FieldBasis' type: array title: Basis description: 'Basis for each top-level field in the JSON output. Per-list-element basis entries are available only when the `parallel-beta: field-basis-2025-11-25` header is supplied.' type: type: string const: json title: Type description: The type of output being returned, as determined by the output schema of the task spec. mcp_tool_calls: anyOf: - items: $ref: '#/components/schemas/McpToolCall' type: array - type: 'null' title: Mcp Tool Calls description: MCP tool calls made by the task. beta_fields: anyOf: - additionalProperties: true type: object - type: 'null' title: Beta Fields description: Deprecated. mcp-server-2025-07-17 is now included directly in the output (e.g. mcp_tool_calls). deprecated: true content: additionalProperties: true type: object title: Content description: Output from the task as a native JSON object, as determined by the output schema of the task spec. output_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Output Schema description: Output schema for the Task Run. Populated only if the task was executed with an auto schema. type: object required: - basis - type - content title: TaskRunJsonOutput description: Output from a task that returns JSON. MonitorEventStreamEvent: properties: event_id: type: string title: Event Id description: Stable identifier for this event. Safe to use for client-side deduplication across pagination and retries. event_group_id: type: string title: Event Group Id description: ID of the event group that owns this event. event_date: anyOf: - type: string - type: 'null' title: Event Date description: Date when this event was produced. ISO 8601 date (YYYY-MM-DD) or partial (YYYY-MM or YYYY). examples: - '2026-04-07' event_type: type: string enum: - event_stream const: event_stream title: Event Type description: Discriminant for the event_stream event variant. default: event_stream output: oneOf: - $ref: '#/components/schemas/TaskRunTextOutput' - $ref: '#/components/schemas/TaskRunJsonOutput' title: Output description: Text or JSON output describing the detected change. discriminator: propertyName: type mapping: json: '#/components/schemas/TaskRunJsonOutput' text: '#/components/schemas/TaskRunTextOutput' type: object required: - event_id - event_group_id - event_date - output title: MonitorEventStreamEvent description: 'Append-only event from an event_stream monitor. Each event represents a distinct material change detected since the previous execution. Events are net-new relative to the cursor; clients should treat them as an append-only log.' McpToolCall: properties: tool_call_id: type: string title: Tool Call ID description: Identifier for the tool call. server_name: type: string title: Server Name description: Name of the MCP server. tool_name: type: string title: Tool Name description: Name of the tool being called. arguments: type: string title: Arguments description: Arguments used to call the MCP tool. content: anyOf: - type: string - type: 'null' title: Content description: Output received from the tool call, if successful. error: anyOf: - type: string - type: 'null' title: Error description: Error message if the tool call failed. type: object required: - tool_call_id - server_name - tool_name - arguments title: McpToolCall description: Result of an MCP tool call. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key