Skip to main content
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:
PhaseSystemPurpose
1TaxonomiesVector-based classification
2ClustersDocument grouping
3AlertsRetriever execution + notifications
4Retriever EnrichmentsField 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
)

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

​
Input Mappings

Input mappings connect document fields to retriever input parameters:
Source TypeDescriptionExample
document_fieldExtract value from the ingested document using a dot-notation path{"source_type": "document_field", "path": "metadata.category"}
constantPass a fixed value to the retriever{"source_type": "constant", "value": "safety_check"}

​
Execution Modes

ModeBehavior
on_ingestExecute automatically when documents are ingested (default)
scheduledExecute on a schedule (does not trigger on ingest)
on_demandExecute 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")

​
Comparison with Other Enrichment Types

FeatureTaxonomiesClustersAlertsRetriever Enrichments
PurposeVector-based classificationDocument groupingNotifications on matchArbitrary retriever pipelines
OutputLabel + score fieldsCluster assignmentsWebhook/Slack/email notificationsConfigurable field write-back
Phase1234
ExecutionParallel per documentBatchParallel per documentSequential per document
Use casesFace matching, entity linkingSegmentation, pattern discoveryContent monitoring, safety checksLLM classification, cross-collection joins