TickerDocs
Tools

watch_event

Stars one event and turns on its alerts, or changes the triggers of an event you starred already.

When to use it

  • You care about one event and want an alert when its price moves, its on-sale date arrives, event week starts or listings run low.
  • The event is starred already and you want other triggers or another email mode: call it again with what changes. A trigger you do not name keeps its setting.
  • You want alerts on every event that meets conditions: use create_view.
  • It replaces update_watch and list_watch_triggers, whose names still answer: see Old names.

Inputs

  • event_id (string, required): The event to star, as search_events or screen_events gives its event_id.
  • triggers (object): The triggers to arm and their settings, keyed by trigger name, as { "pct_move": { "enabled": true, "params": { "threshold": 20 } } }. The input lists every trigger, what it alerts on, whether it is on by default, and each setting's range. On a new star, a trigger you do not name takes its setting from your watch defaults; on a starred event it keeps its setting.
  • notification_mode (string): How this event's alerts reach your email. instant sends each alert as it comes. batched sends the alerts together in one email. muted records the alerts and does not send them. Until 2026-11-30 the server also accepts digest, the old name of batched, and stores it as batched; a response always says batched. Send batched. Leave it out to use your watch defaults. One of instant, batched, muted, digest.

Examples

Watch the Zach Bryan show at Madison Square Garden.

{ "event_id": "ev5n7c2w9d4k" }

Star this Lakers game and alert me if the lowest price moves 20% in a week.

{
  "event_id": "ev8k2m4q7x1a",
  "triggers": {
    "pct_move": {
      "enabled": true,
      "params": { "metric": "lowest", "window": "7d", "threshold": 20 }
    }
  }
}

I already watch this game. Turn off the unusual price move alert and send its alerts in one email.

{
  "event_id": "ev8k2m4q7x1a",
  "triggers": { "price_z": { "enabled": false } },
  "notification_mode": "batched"
}

What comes back

  • The starred event: event_id, event_name, venue and date, current prices, and the triggers and notification_mode it uses.
  • alerts_live is false when your plan keeps this event from alerting.
  • dormanted names the events that stopped alerting because this one took their place. They stay starred. Tell the person when it is not empty.
  • already_watched is true when the event was starred before. Then the triggers and mode you passed are saved, and the ones you left out stay as they were.
  • A value outside its range is refused, with an error that names the field and its min and max. Nothing is starred.

Limits and quota

  • Changes or deletes something you own.
  • Reaches beyond Ticker: it can send alerts or read the web.
  • Each call spends one MCP request.
  • Saved Views and starred events share one Limit on your plan. You can star any number of events, but only the newest ones inside that Limit alert.
  • A watch is archived when its event ended more than a week ago. It stops alerting then.

On this page