Skip to main content
POST
Create Watch
Credits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.

Overview

Creates a saved monitor that runs on every data sync. Five watch types (mark, portfolio, owner, class, similarity) share a single query shape; watch_type selects which scoping field is required. Your plan’s watch limit is enforced before insert. To see what a watch would catch before you create it, use Preview Watch, which returns the actual matching marks by default. Requires the portfolios:manage scope.

Body Parameters

string
required
Display name (1-255 chars).
string
required
One of mark, portfolio, owner, class, similarity. Each type requires a specific field to be populated, see the Watches guide for the table.
object
required
Watch query DSL.
string
Currently only always_per_alert is supported: one delivery per alert. Any other value returns 400. Digest modes are planned but not yet available. See delivery_mode.
object
Free-form metadata (max 8KB).

Response

Returns the created Watch with status 201.
string
Watch ID (wat_*).
string
Always "watch".
string
Display name.
string
One of the five types.
object
Saved query DSL, in the stored form: version: "v3", the resolved similarity when the query has q, and min_tier (default related).
string
Delivery cadence.
string
Initial status: active.
integer | null
Null on create.
string | null
Null on create.
object
Echoed back.
string
ISO timestamp.
string
ISO timestamp.
object[]
Present only when the request used a deprecated key (strategies, min_match_tier); the watch is kept as a legacy watch until re-saved without them. Each entry has param (e.g. query.strategies), replacement (e.g. query.similarity) and sunset (2026-12-28), the date the old key starts returning 400 with code unknown_parameter.
string
Request identifier.

Code Examples