> ## 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.
# Alerts
> Monitor ingested content with retriever-powered alerts and real-time notifications
Alerts let you attach retriever pipelines to collections so that every ingested document is automatically checked against your search criteria. When matches are found, notifications fire to your configured channels (webhook, Slack, or email).
## How It Works
1. **Create** a retriever that defines your search criteria (e.g., semantic similarity, attribute filters)
2. **Create** an alert referencing that retriever, with notification channels configured
3. **Attach** the alert to a collection via `alert_applications` with input mappings
4. **Ingest** documents — alerts execute automatically during post-processing (Phase 3)
5. **Receive** notifications when matches are found
## Architecture
Alerts execute during the post-processing pipeline after document ingestion completes:
| Phase | System | Purpose |
| ----- | --------------------- | --------------------------------------- |
| 1 | Taxonomies | Vector-based classification |
| 2 | Clusters | Document grouping |
| **3** | **Alerts** | **Retriever execution + notifications** |
| 4 | Retriever Enrichments | Field write-back |
### Parallel Execution
Within a single alert, document-level retriever calls execute **in parallel** as independent Ray tasks. If a batch ingests 100 documents, all 100 retriever calls fan out simultaneously rather than running sequentially. Results are aggregated after all calls complete, and a single notification is sent if any document produced matches.
Multiple alerts on the same collection execute **sequentially** to avoid race conditions in notification delivery.
## Configuration
### Create an Alert
```python Python theme={null}
from mixpeek import Mixpeek
client = Mixpeek(api_key="your-api-key")
alert = client.alerts.create(
name="safety_content_monitor",
description="Detect potentially harmful content on ingestion",
retriever_id="ret_safety_classifier",
notification_config={
"channels": [
{
"channel_type": "webhook",
"config": {"url": "https://your-app.com/webhooks/alerts"}
},
{
"channel_type": "slack",
"config": {"channel": "#content-alerts"}
}
],
"include_matches": True,
"include_scores": True
},
enabled=True
)
```
```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/alerts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Namespace: your-namespace" \
-H "Content-Type: application/json" \
-d '{
"name": "safety_content_monitor",
"retriever_id": "ret_safety_classifier",
"notification_config": {
"channels": [
{"channel_type": "webhook", "config": {"url": "https://your-app.com/webhooks/alerts"}},
{"channel_type": "slack", "config": {"channel": "#content-alerts"}}
],
"include_matches": true,
"include_scores": true
},
"enabled": true
}'
```
### Attach to a Collection
Attach alerts to collections via `alert_applications` when creating or updating a collection:
```python Python theme={null}
client.collections.create(
collection_name="user_uploads",
source={"type": "bucket", "bucket_ids": [bucket_id]},
feature_extractor={
"feature_extractor_name": "text_extractor",
"version": "v1",
"input_mappings": {"text": "content"},
},
alert_applications=[
{
"alert_id": alert.alert_id,
"execution_mode": "on_ingest",
"input_mappings": [
{
"input_key": "query_text",
"source": {
"source_type": "document_field",
"path": "content"
}
}
]
}
]
)
```
```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/collections \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Namespace: your-namespace" \
-H "Content-Type: application/json" \
-d '{
"collection_name": "user_uploads",
"source": {"type": "bucket", "bucket_ids": ["bucket_id"]},
"feature_extractor": {
"feature_extractor_name": "text_extractor",
"version": "v1",
"input_mappings": {"text": "content"}
},
"alert_applications": [
{
"alert_id": "alert_id",
"execution_mode": "on_ingest",
"input_mappings": [
{
"input_key": "query_text",
"source": {"source_type": "document_field", "path": "content"}
}
]
}
]
}'
```
### Input Mappings
Input mappings connect document fields to retriever input parameters:
| Source Type | Description | Example |
| ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| `document_field` | Extract value from the ingested document using a dot-notation path | `{"source_type": "document_field", "path": "metadata.category"}` |
| `constant` | Pass a fixed value to the retriever | `{"source_type": "constant", "value": "safety_check"}` |
### Execution Modes
| Mode | Behavior |
| ----------- | ----------------------------------------------------------- |
| `on_ingest` | Execute automatically when documents are ingested (default) |
| `scheduled` | Execute on a schedule (does not trigger on ingest) |
| `on_demand` | Execute only when manually triggered |
## Notification Channels
### Webhook
```json theme={null}
{
"channel_type": "webhook",
"config": {"url": "https://your-app.com/webhooks/alerts"}
}
```
The webhook receives a JSON payload with alert details, matched documents, and scores.
### Slack
```json theme={null}
{
"channel_type": "slack",
"config": {"channel": "#alerts-channel"}
}
```
### Email
```json theme={null}
{
"channel_type": "email",
"config": {"to": ["alerts@your-company.com"]}
}
```
## Monitoring Executions
Track alert execution history to monitor performance and debug issues:
```python Python theme={null}
executions = client.alerts.list_executions(alert_id="alert_id")
for execution in executions.results:
print(f"Execution {execution.execution_id}: "
f"triggered={execution.triggered}, "
f"matches={execution.match_count}, "
f"duration={execution.duration_ms}ms")
```
```bash cURL theme={null}
curl https://api.mixpeek.com/v1/alerts/ALERT_ID/executions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Namespace: your-namespace"
```
## Comparison with Other Enrichment Types
| Feature | Taxonomies | Clusters | Alerts | Retriever Enrichments |
| --------- | ----------------------------- | ------------------------------- | --------------------------------- | ------------------------------------------ |
| Purpose | Vector-based classification | Document grouping | Notifications on match | Arbitrary retriever pipelines |
| Output | Label + score fields | Cluster assignments | Webhook/Slack/email notifications | Configurable field write-back |
| Phase | 1 | 2 | 3 | 4 |
| Execution | Parallel per document | Batch | Parallel per document | Sequential per document |
| Use cases | Face matching, entity linking | Segmentation, pattern discovery | Content monitoring, safety checks | LLM classification, cross-collection joins |