Watches

Watches are automated, recurring agent runs that execute on a schedule or in response to external events.

What Are Watches?

A watch connects an agent to a trigger — either a cron schedule or an incoming event — and runs the agent automatically each time the trigger fires. Watches let you automate recurring tasks like monitoring marketplace metrics, generating reports, or alerting on changes, without manually starting a conversation.

Each watch execution creates a record you can inspect, so you always have visibility into what ran, when, and whether it succeeded.

Creating a Watch

1. Navigate to Watches in the Insulin sidebar
2. Click Create Watch
3. Configure the watch:
   • Name — A descriptive name (e.g., “Daily Revenue Summary”)
   • Description — What this watch does
   • Agent — The agent to run when the watch triggers
   • Mode — How the watch is triggered (see Execution Modes)
   • Schedule — A cron expression for cron-mode watches
   • Filter — An optional filter expression to skip irrelevant events
4. Click Save

The watch starts running on its next scheduled time (or immediately begins listening for events in push mode). If no agent is specified, the watch defaults to the built-in Insulin agent.

Execution Modes

Watches support three modes:

Most watches use cron mode for time-based automation or push mode for event-driven automation.

Cron Scheduling

Cron expressions define when a watch runs. Standard cron syntax is supported:

The next scheduled run time is displayed on the watch detail page.

Filter Expressions

Filters let you control which events actually trigger an agent run. When an event arrives (in push mode) or a cron tick fires, the filter expression is evaluated against the event payload. If the filter returns false, the execution is skipped and recorded as filtered.

Filters use filtrex syntax — a safe, sandboxed expression language. The event payload is available under the event namespace.

Examples:

event.source == "aws-marketplace"

event.amount > 1000

event.action == "entitlement_created" and event.partner == "AWS"

lower(event.status) == "active"

Available functions: lower(), upper(), includes() (checks if an array contains a value).

Dot notation is supported for nested fields: event.buyer.name, event.offer.info.commits.

Execution History

Every time a watch fires, an execution record is created. Each execution has one of these statuses:

To view execution history:

1. Open a watch from the Watches list
2. Scroll to the Executions section
3. Each execution shows its status, timestamp, and (for failed runs) the error message

Managing Watches

From the watch detail page you can:

• Enable / Disable — Pause a watch without deleting it. Disabled watches do not trigger.
• Trigger manually — Run the watch immediately with an optional payload, without waiting for the next scheduled time.
• Edit — Update the name, description, schedule, filter, or assigned agent.
• Delete — Permanently remove the watch and its execution history.

Use Cases

• Marketplace monitoring — Schedule an agent to check for new entitlements or expiring offers daily and summarize changes.
• Automated alerts — Push events from your cloud marketplace into a watch that runs an agent to evaluate severity and notify your team.
• Recurring reports — Run a data analyst agent weekly to generate revenue or usage reports.
• Co-sell pipeline tracking — Monitor partner referrals on a schedule and flag stale opportunities.