WatchList

Overview

The WatchList is a proactive monitoring system that keeps an eye on volatile information — stock prices, weather forecasts, news headlines, web pages, API endpoints, or even recurring AI queries — and notifies you automatically when a trigger condition is met.

Instead of manually checking a website every morning or refreshing a stock ticker throughout the day, you set up a watch once and let Yukkai do the polling for you. When the condition fires, you receive a notification with the relevant context.

WatchList vs. Scheduling — WatchList is for recurring checks on external data that changes over time. If you simply need a one-time reminder or a scheduled prompt at a specific date/time, use the Scheduling tool instead.

---

How it works

A watch is composed of three layers:

Layer	Description	Example
Source	Where the data comes from	A web page, an API endpoint, an LLM query
Trigger	The condition that fires the notification	Price drops below $150, page content changes
Delivery	How you're notified	Telegram message via Yukkai

Source types

Each watch pulls data from one of the following source types:

• webPage — Yukkai fetches and analyzes a web page at regular intervals. The page content is passed to an extraction prompt that isolates the value you care about.
• api — Yukkai calls an API endpoint (GET by default) and evaluates the response against your trigger.
• local — A local provider on your machine (e.g., a script or system check).
• llmQuery — Yukkai runs a natural-language prompt through an AI model on a schedule. The model's answer is compared against the trigger. This is useful for open-ended questions like "Is there any breaking news about [company] today?"

Trigger types

Trigger	What it does	trigger_value
dailyAt	Fires once at a specific hour each day	Hour (0–23), e.g. "8"
valueChanged	Fires when the monitored value changes from the previous check	—
percentChange	Fires when the value moves by a percentage threshold	e.g. "5" (5%)
newItemsDetected	Fires when new items appear in a feed/list	—
contains	Fires when the content contains specific text	Text string, e.g. "sold out"
threshold	Fires when a numeric value crosses a threshold	Number, e.g. "150"

Each trigger type comes with a sensible default polling frequency and daily notification cap. You only need to override these if you have a specific requirement.

Categories

Categories help organize watches and provide sensible defaults:

• horoscope — Daily horoscope checks
• stock — Stock price monitoring
• weather — Weather alerts
• news — News headline monitoring
• webPage — General web page watching
• api — API response monitoring
• local — Local system checks
• custom — Anything else

---

How to use it

Creating a watch

All watches are created through natural-language instructions or structured parameters. Here's what you'll provide:

1. A description of what to monitor — This becomes the query field and should be a human-readable summary of your intent.
2. The data source — A URL, an API endpoint, or an LLM prompt, depending on the source type.
3. The trigger condition — What should cause a notification to fire.
4. (Optional) Frequency and limits — How often to check and the maximum notifications per day.

Yukkai takes care of the rest: scheduling the checks, comparing values, and sending you a message when the trigger fires.

Managing watches

• List all watches — View every active watch along with its current state and last-checked timestamp.
• Update a watch — Change the polling frequency, daily notification cap, or enable/disable a watch without deleting it.
• Delete a watch — Permanently remove a watch you no longer need.
• Run a watch — Force an immediate check, bypassing the normal schedule. This is great for testing a newly created watch.

---

Examples

Stock price alert

"Notify me when Apple's stock drops below $150."

Parameter	Value
Category	stock
Source type	webPage or api
Trigger	threshold
Trigger value	150
Direction	below

Daily weather briefing

"Send me the weather forecast every morning at 7 AM."

Parameter	Value
Category	weather
Source type	llmQuery
Trigger	dailyAt
Trigger value	7

Web page change detection

"Tell me when the release notes page for [product] changes."

Parameter	Value
Category	webPage
Source type	webPage
Source URL	The page to watch
Trigger	valueChanged

News keyword monitoring

"Alert me if any news mentions 'acquisition' for [company]."

Parameter	Value
Category	news
Source type	llmQuery
Trigger	contains
Trigger value	acquisition

API threshold monitoring

"Notify me when the API response time exceeds 2000ms."

Parameter	Value
Category	api
Source type	api
Source URL	The API endpoint
Trigger	threshold
Trigger value	2000
Direction	above

---

Tips

Choose the right trigger

• Use valueChanged when you want to know anything changed — ideal for release notes, changelogs, or status pages.
• Use threshold for numeric values like prices, temperatures, or response times.
• Use percentChange when the absolute value matters less than the rate of change (e.g., a stock swinging 10% in either direction).
• Use newItemsDetected for feeds and lists where new entries are added over time.
• Use contains when you're waiting for a specific keyword or phrase to appear.

Avoid notification fatigue

Every trigger has a built-in default for frequency_minutes and max_per_day. These are designed to prevent spam. Only lower these if you genuinely need faster alerts — for example, a stock alert during trading hours might warrant a 5-minute check, while a daily news digest is fine at once per day.

Test with run

After creating a new watch, use the run action to force an immediate check. This confirms that your source is reachable, your extraction prompt works, and the trigger evaluates correctly — all before waiting for the first scheduled poll.

Use llmQuery for complex monitoring

When a simple value comparison isn't enough — for example, "Is there any negative sentiment about my company in today's news?" — the llmQuery source type lets an AI model interpret the data. The model receives your prompt, processes the information, and its answer is checked against the trigger.

Disable instead of delete

If you only need to pause a watch temporarily (e.g., over the weekend or during a holiday), use update to set enabled: false. The watch stays configured and can be re-enabled instantly without re-entering all the parameters.

Keep extraction prompts specific

For webPage watches, the extraction prompt determines what data Yukkai pulls from the page. A vague prompt like "get the price" may return inconsistent results. A specific prompt like "Extract the current Bitcoin price in USD from the page content" will be far more reliable.

---

WatchList is part of Yukkai's Automation category. For scheduled reminders and calendar-based triggers, see Scheduling.