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, Mixpeek notifies your configured channels (webhook, Slack, or email) or processes the matching objects into a collection you define.

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

Alerting on a Taxonomy-Assigned Category

If your goal is “notify my team when content lands in a specific category” rather than a semantic search, the retriever in step 1 does not need embeddings at all. Taxonomies run in Phase 1, before Alerts in Phase 3 (see Architecture below), so by the time your alert’s retriever executes, any category a taxonomy assigned is already a field on the document. A retriever with a single filter stage is enough:

{
  "stage_name": "attribute_filter",
  "stage_type": "filter",
  "config": {
    "stage_id": "attribute_filter",
    "parameters": {
      "field": "metadata.category",
      "operator": "eq",
      "value": "counterfeit"
    }
  }
}

Replace metadata.category with the field_path your taxonomy’s enrichment_fields writes (see Taxonomies), and value with the category you want to alert on. Use the in operator instead of eq to alert on more than one category at once. See Attribute Filter for the full operator list.

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

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:

Python

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 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": ["[e-mail]"]}
}

Batch

The batch channel processes the bucket objects behind the matching documents into a collection you define.

{
  "channel_type": "batch",
  "config": {"collection_id": "col_alert_frames"}
}

After the batch that fired the alert completes, Mixpeek submits one batch per source bucket. Each batch holds the objects whose documents matched. The output documents keep lineage back to those objects. To copy capture fields such as captured_at onto the output documents, list them in the target collection’s field_passthrough (see Feature extractors).

Key	Required	Description
collection_id	Yes	Collection that receives the processed objects. Mixpeek also accepts target_collection_id.
bucket_id	No	Limits the batch to objects from this bucket. Defaults to the bucket in each matching document’s lineage.
dedup_strategy	No	skip (default), replace, or force. With skip, Mixpeek processes an object once, even when it matches again.

The target collection must meet three conditions:

• It reads from a bucket, and that bucket holds the matched objects.
• It is user-defined. Names that start with _ or mxp_ are system collections.
• It differs from the collection the alert watches. Processing back into it would fire the alert again.

Mixpeek validates the config keys when you save the alert. A missing collection_id, an unknown key, or an invalid dedup_strategy returns a 422. Mixpeek checks the three conditions after the alert fires.

The batch that fired the alert must leave the target out. A batch created without collection_ids covers every enabled collection that reads the bucket, the target included. POST /v1/buckets/{bucket_identifier}/objects?auto_process=true and POST /v1/buckets/{bucket_identifier}/objects/batch?auto_process=true create their batch this way. The target then holds the objects’ documents before the alert fires, so with dedup_strategy: skip the batch the channel submits skips those objects. To exercise the channel, create the batch with POST /v1/buckets/{bucket_identifier}/batches and list the collections to process in collection_ids, leaving the target out.

Attach a second alert to the target collection to monitor the processed output. It is an ordinary retriever alert with the same channels as any other.

Each batch task records its origin in additional_data.triggered_by_alert. The record holds the alert ID, the execution ID, the matching document IDs, and each object’s capture fields (captured_at, segment_index, segment_duration_seconds) when the source is an RTSP feed.

If the batch cannot start, for example because the target collection reads from another collection, Mixpeek sends an alert.execution.failed webhook event with the reason. Mixpeek retries transient errors and stops after 3 attempts.

Monitoring Executions

Track alert execution history to monitor performance and debug issues:

Python

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

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, or a batch into a collection	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