> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers vs Alerts

> Triggers run work on a schedule. Alerts watch for a condition and tell you. Which one you want, and where the seam is.

A **trigger** runs work. An **alert** watches and tells you.

Both are configured per namespace and both can end in a Slack message, which is why they get confused.

## Which one do I want

| You want to | Use |
| - | - |
| Re-cluster a collection every night | Trigger |
| Re-run enrichment after a taxonomy changes | Trigger |
| Re-process a batch that failed | Trigger |
| Know when a search starts returning nothing | Alert |
| Know when a search starts returning too much | Alert |
| Get a Slack message when a data-plane condition is met | Alert |

The short test: if the outcome is **work that happened**, you want a trigger. If the outcome is **someone finding out**, you want an alert.

## Triggers

A trigger is a schedule plus an action.

| `trigger_type` | Fires |
| - | - |
| `cron` | On a cron expression |
| `interval` | Every N seconds |
| `event` | When a named event occurs |
| `conditional` | When a condition evaluates true |

| `action_type` | Runs |
| - | - |
| `cluster` | Clustering over a collection |
| `taxonomy_enrichment` | Taxonomy enrichment |
| `batch_rerun` | A batch again |
| `collection_trigger` | A collection's processing |
| `retriever_execution` | A saved retriever with fixed inputs, judged against acceptance criteria |
| `alert_evaluation` | One retriever alert, on the trigger's schedule |

```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/triggers \
  -H "Authorization: Bearer YOUR_MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly recluster",
    "trigger_type": "cron",
    "schedule_config": {"cron_expression": "0 3 * * *", "timezone": "UTC"},
    "action_type": "cluster",
    "action_config": {"cluster_id": "clust_your_cluster_id"}
  }'
```

A trigger's output is its run history. Read it to see what ran and what failed.

## Alerts

An alert is a source plus a condition plus somewhere to send the news.

| `source` | Watches |
| - | - |
| `retriever` | A retriever's results. Set `trigger_on` to `results` or `no_results` |
| `system` | A built-in data-plane condition, via `system_condition` |

`notification_config.channels` takes one or more of `webhook`, `slack`, and `email`.

```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/alerts \
  -H "Authorization: Bearer YOUR_MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search returning nothing",
    "source": "retriever",
    "retriever_id": "ret_your_retriever_id",
    "trigger_on": "no_results",
    "notification_config": {
      "channels": [
        {"channel_type": "slack", "config": {"webhook_url": "https://hooks.slack.com/..."}}
      ]
    }
  }'
```

## When a retriever alert is evaluated

`execution_mode` takes `on_ingest`, `scheduled`, or `on_demand`.

`on_ingest` is what most alerts want. It rides the ingestion pipeline, so the alert is evaluated against data at the moment that data lands. Every retriever alert that is not `on_demand` is also evaluated every 5 minutes, which is how an alert on data written directly through the API fires.

To evaluate an alert on a schedule of your own, create a trigger whose action is `alert_evaluation`. While that trigger is active, the alert is evaluated on its schedule in the trigger's namespace and the 5-minute evaluation leaves it alone there. Pause or delete the trigger to hand it back.

```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/triggers \
  -H "Authorization: Bearer YOUR_MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_type": "cron",
    "schedule_config": {"cron_expression": "0 * * * *", "timezone": "UTC"},
    "action_type": "alert_evaluation",
    "action_config": {"alert_id": "alt_your_alert_id"}
  }'
```

A scheduled evaluation behaves like any other: the alert notifies when its condition starts to hold, stays quiet while it keeps holding unless `renotify_interval_seconds` is set, and respects `cooldown_seconds`. Each run appears in the trigger's run history.

`on_demand` alerts are never evaluated automatically; call them yourself.

## Related

> [card] [Webhooks](https://docs.mixpeek.com/docs/operations/webhooks.md)
>
> Where an alert's `webhook` channel delivers.

> [card] [Change feed](https://docs.mixpeek.com/docs/operations/change-feed.md)
>
> Reading what changed, rather than being told.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.