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_applicationswith input mappings - Ingest documents — alerts execute automatically during post-processing (Phase 3)
- 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: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: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
Conditions
trigger_on decides what the alert’s retriever has to return for the alert to fire. The same condition is applied wherever the alert runs: when a document is written, in the batch pipeline, and on the periodic sweep.
Each run of the retriever is judged on its own rows. A retriever that ends in an aggregate stage returns its groups as rows, so
min_count: 3 means three groups and a threshold reads the first group’s metrics. A run that errors or comes back degraded gives no verdict, so it neither fires a no_results alert nor clears one that is firing.
A threshold compares one field of the first row the retriever returns. The field can be a top-level key such as score or an aggregate column, a dot path such as metadata.price, or a bare name that is looked up in the row’s metadata. The operators are gt, gte, lt, lte, eq and ne. A missing field, or a value of a different type, does not fire.
min_count or threshold with trigger_on: no_results is refused with a 422 that names the field.
Cooldown and Re-notify
cooldown_seconds keeps an alert from notifying again within that many seconds of its last notification. A fire inside the cooldown is recorded with suppressed: cooldown and sends nothing. The cooldown is shared by every path, so an alert that fired at ingest stays quiet on the sweep until the cooldown has passed.
renotify_interval_seconds applies to the sweep. While the condition stays true, the alert notifies again at this interval, and never sooner than the cooldown. Leave it unset to be told once each time the condition starts to hold.
last_fired_at on the alert shows when it last notified.
Alert Inputs
inputs are the retriever inputs the alert runs with. The sweep has no document to map from, so it runs the retriever with exactly these. At ingest, inputs mapped from the document are laid over them, so a document field wins where both set the same key.
This is how a time window carries over to the sweep. A retriever filter on {{time_ago(minutes=INPUT.window_minutes)}} with "inputs": {"window_minutes": 60} on the alert looks back one hour whichever path runs it.
Attach to a Collection
Attach alerts to collections viaalert_applications when creating or updating a collection:
Input Mappings
Input mappings connect document fields to retriever input parameters:Execution Modes
Notification Channels
Webhook
Slack
Batch
Thebatch channel processes the bucket objects behind the matching documents into a collection you define.
captured_at onto the output documents, list them in the target collection’s field_passthrough (see Feature extractors).
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
_ormxp_are system collections. - It differs from the collection the alert watches. Processing back into it would fire the alert again.
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:Default Alerts
Every new organization gets a set of system alerts, one per built-in condition, across all its namespaces. They email the organization’snotifications_email, which is set to the signup address when the organization is created and can be changed with PATCH /v1/organizations.
List them with
GET /v1/organizations/alerts, and turn one on or off with PATCH /v1/organizations/alerts/{alert_identifier} and {"enabled": true} or false. Provisioning finds each default by name, so a default you change or disable is not recreated.
Each condition is evaluated by a saved retriever in the namespace, named system-<condition> (for example system-collection-stale) and tagged system-alert, over the system collection that records it. Run it like any retriever to see which collections, batches or retrievers meet the condition now. Mixpeek never overwrites a shipped retriever you have edited.