Alerts

Alerts: batch ingested documents checked against retriever in parallel, matches trigger webhook, Slack, or email 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

Create a retriever that defines your search criteria (e.g., semantic similarity, attribute filters)
Create an alert referencing that retriever, with notification channels configured
Attach the alert to a collection via alert_applications with input mappings
Ingest documents — alerts execute automatically during post-processing (Phase 3)
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

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
)

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:

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"
                    }
                }
            ]
        }
    ]
)

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

{
  "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

{
  "channel_type": "slack",
  "config": {"channel": "#alerts-channel"}
}

Email

{
  "channel_type": "email",
  "config": {"to": ["alerts@your-company.com"]}
}

Monitoring Executions

Track alert execution history to monitor performance and debug issues:

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")

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

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

How It Works

Architecture

Parallel Execution

Configuration

Create an Alert

Attach to a Collection

Input Mappings

Execution Modes

Notification Channels

Webhook

Slack

Email

Monitoring Executions

Comparison with Other Enrichment Types

​How It Works

​Architecture

​Parallel Execution

​Configuration

​Create an Alert

​Attach to a Collection

​Input Mappings

​Execution Modes

​Notification Channels

​Webhook

​Slack

​Email

​Monitoring Executions

​Comparison with Other Enrichment Types

How It Works

Architecture

Parallel Execution

Configuration

Create an Alert

Attach to a Collection

Input Mappings

Execution Modes

Notification Channels

Webhook

Slack

Email

Monitoring Executions

Comparison with Other Enrichment Types