TickerDocs
Tools

list_watchlist

Lists the events you watch, with current prices, the triggers on each, and how many alerts each has made.

When to use it

  • You want to see what you watch, and which watches still alert.
  • You want the event_id to change or remove a watch with watch_event or unwatch_event.
  • You want your saved screens: use list_views.

Inputs

  • page (integer, default 1): The page of results.
  • limit (integer, default 50): Rows per page. A number above 100 gives 100 rows.
  • search (string): Part of an event name. Only events whose name contains it come back. Case does not matter.
  • sort (string, default created_at): What to order by: when you starred the event, the event date, the last alert, or the event name. One of created_at, utc_date, last_matched_at, event_name.
  • order (string, default desc): The direction of the sort: asc for earliest or A first, desc for latest or Z first. One of asc, desc.
  • include_archived (boolean, default false): The older name of archived: true means include, false means exclude.
  • archived (string, default exclude): Watches whose event ended more than a week ago: exclude (the default) leaves them out, include adds them, only reads them alone. They no longer alert and take no edits. One of exclude, include, only, true, false.

Examples

What events am I watching?

{}

Which of my watched events come up first?

{ "sort": "utc_date", "order": "asc", "limit": 10 }

Did my Zach Bryan watch from last month ever alert?

{ "search": "Zach Bryan", "include_archived": true }

What comes back

  • One row per watch in data: event_id, event_name, event_url, venue, utc_date, and current numbers such as lowest_price_current, median_price_current and listings_current.
  • triggers and notification_mode: what the watch alerts on, and how its alerts reach your email.
  • match_count and last_matched_at: how many alerts the watch has made, and when the last one came.
  • alerts_live is false when your plan keeps the watch from alerting. stale is true when the event's prices are more than three days old.
  • archived_at is set on a watch whose event ended more than a week ago.
  • total and totalPages, and live_count, how many of your watches can alert now.

Limits and quota

  • Reads only: it changes nothing.
  • Each call spends one MCP request.
  • A sort by last_matched_at orders the rows inside each page only. The pages follow the order in which you starred the events.

On this page