--- title: "List Org-Scoped Alerts" method: POST path: "/v1/organizations/alerts/list" tags: ["Alerts"] --- # List Org-Scoped Alerts `POST /v1/organizations/alerts/list` ## Request - Base URL: `https://api.mixpeek.com` - URL: `https://api.mixpeek.com/v1/organizations/alerts/list` - Auth: HTTP bearer List all organization-level alerts (scoped by internal_id). ## Query parameters - `limit` integer, nullable - `page_size` integer, nullable - `offset` integer, nullable - `page` integer, nullable - `cursor` string, nullable - `next_cursor` string, nullable - `after` string, nullable - `include_total` boolean ## Request body - ListAlertsRequest: Request model to list alerts. - `search` string, nullable: Search term for wildcard search across alert_id, name, description - `filters` LogicalOperatorInput: Represents a logical operation (AND, OR, NOT) on filter conditions. Allows nesting with a defined depth limit. Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}). - `AND` union[], nullable: Logical AND operation - all conditions must be true - union - LogicalOperatorInput (recursive) - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required: Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem. - `value` union, required: Value to compare against - DynamicValue: A value that should be dynamically resolved from the query request. - … - unknown - `OR` union[], nullable: Logical OR operation - at least one condition must be true - union - LogicalOperatorInput (recursive) - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required: Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem. - `value` union, required: Value to compare against - DynamicValue: A value that should be dynamically resolved from the query request. - … - unknown - `NOT` union[], nullable: Logical NOT operation - all conditions must be false - union - LogicalOperatorInput (recursive) - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required: Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem. - `value` union, required: Value to compare against - DynamicValue: A value that should be dynamically resolved from the query request. - … - unknown - `case_sensitive` boolean, nullable: Whether to perform case-sensitive matching - `sort` SortOption: Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending) - `field` string, required: Field to sort by, supports dot notation for nested fields - `direction` 'asc' | 'desc': Sort direction options. - `case_sensitive` boolean: If True, filters and search will be case-sensitive ## Response `200` Successful Response - ListAlertsResponse: Response model for listing alerts. - `results` AlertResponse[], required: List of alerts - `alert_id` string: Unique identifier for the alert - `namespace_id` string, nullable: Namespace this alert belongs to - `name` string, required: Human-readable name for the alert - `description` string, nullable: Optional description of what this alert monitors - `source` 'retriever' | 'system': Where an alert's trigger decision comes from. Send the lowercase wire value (shown in quotes), NOT the member name. "retriever": runs a retriever against ingested data and fires on (no-)match. "Does my data contain something?" "system": evaluates a built-in data-plane metric against a threshold. "Is my pipeline / data healthy?" No retriever involved. - `retriever_id` string, nullable: ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits. - `trigger_on` 'results' | 'no_results': For retriever-source alerts, which retriever outcome fires the alert. Send the lowercase wire value (shown in quotes), NOT the member name. "results": fire when the retriever returns matches (the classic behavior). "no_results": fire when the retriever returns nothing — catches a retriever that has silently gone dark (empty collection, broken pipeline). "results" can be narrowed by two alert fields: ``min_count`` (at least that many rows) and ``threshold`` (a field of the FIRST result meets a comparison, for example ``score >= 0.9`` or an aggregate's ``count > 100``). They are fields rather than further values here so that a release which predates them still reads the alert, as a plain "results" alert. - `min_count` integer, nullable: With trigger_on='results': fire only when the retriever returns at least this many rows. - `threshold` AlertThreshold: A comparison on one field of the first result (with ``trigger_on='results'``). - `field` string, required: Field of the first result to compare. A top-level key (score, an aggregate column) or a dot path; a bare name not at the top level is also read from the result's metadata. - `operator` 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'ne', required: Comparison applied as . - `value` unknown, required - `inputs` object: Retriever inputs this alert runs with. The sweep runs the retriever with exactly these, so a templated window such as {{time_ago(minutes=INPUT.window_minutes)}} keeps its window. At ingest, inputs mapped from the document override keys set here. - `cooldown_seconds` integer: After the alert fires, further fires within this many seconds are suppressed, on every path. 0 means no cooldown. - `renotify_interval_seconds` integer, nullable: While the condition stays true, notify again at this interval. Unset means notify once per rise. Never fires inside cooldown_seconds. - `last_fired_at` string, date-time, nullable: When the alert last notified. Set by the platform; read-only. - `system_condition` SystemCondition: A built-in data-plane condition for a system-source alert. The condition `type` selects which metric is evaluated; `params` carries per-type thresholds (e.g. ``stall_minutes``, ``latency_multiplier``, ``error_rate_threshold``, ``drop_fraction``). All params are optional and fall back to sensible defaults in the evaluator. Attributes: type: Which system condition to evaluate. params: Optional per-condition threshold overrides. - `type` 'collection_empty' | 'batch_failed' | 'batch_stalled' | 'retriever_latency' | 'retriever_no_results' | 'batch_error_rate' | 'collection_drift' | 'retriever_accuracy' | 'retriever_alignment_regression' | 'task_queue_degraded' | 'dlq_growth' | 'provider_quota_exhausted' | 'retriever_no_interactions' | 'collection_stale' | 'budget_threshold' | 'ingest_stalled', required: Built-in data-plane conditions a system-source alert can watch. - `params` object: Per-condition threshold overrides (evaluator supplies defaults) - `namespace_selector` NamespaceSelector: Selects which namespaces an org-level alert applies to. mode=all → every namespace in the org (resolved at evaluation time). mode=selected → an explicit allow-list; must be non-empty. Attributes: mode: ``all`` or ``selected``. namespace_ids: Allow-list used when mode=selected. - `mode` 'all' | 'selected': How an org-level alert chooses which namespaces it applies to. - `namespace_ids` string[]: Namespace IDs the alert applies to (when mode=selected) - `notification_config` AlertNotificationConfig, required: How and where to send notifications when an alert is triggered. Defines the notification channels and what information to include in the notification payload. Attributes: channels: List of channels to send notifications to include_matches: Whether to include matched documents in the payload include_scores: Whether to include similarity scores in the payload template_id: Optional template for formatting the notification - `channels` NotificationChannelConfig[], required: List of notification channels to send alerts to - `channel_type` string, required: Type of channel: 'webhook', 'slack', 'email', or 'batch'. 'batch' processes the bucket objects behind the matching documents through a user-defined collection (config: collection_id, and optionally bucket_id and dedup_strategy). - `channel_id` string, nullable: Reference to a pre-configured notification channel in the organization - `config` object, nullable: Channel-specific configuration overrides (e.g., webhook URL, Slack channel, or the target collection for a 'batch' channel) - `include_matches` boolean: Include matched documents in notification payload - `include_scores` boolean: Include similarity scores in notification payload - `template_id` string, nullable: Optional notification template for formatting - `enabled` boolean: Whether the alert is active and will execute - `created_at` string, date-time, nullable: Timestamp when the alert was created - `updated_at` string, date-time, nullable: Timestamp when the alert was last updated - `metadata` object: Additional user-defined metadata for the alert - `pagination` PaginationResponse, required: PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true - `total` integer, nullable: Number of items matching the request across all pages, filters included. null unless the request set include_total=true (in the body or as ?include_total=true). A counted request that matches nothing returns 0. - `page` integer, nullable - `page_size` integer, nullable - `total_pages` integer, nullable: Number of pages at page_size. null unless include_total=true. - `next_page` string, nullable - `previous_page` string, nullable - `next_cursor` string, nullable - `total_count` integer, required: Total number of alerts matching query - `stats` AlertListStats: Aggregate statistics for a list of alerts. - `total_alerts` integer: Total number of alerts - `enabled_alerts` integer: Number of enabled alerts - `disabled_alerts` integer: Number of disabled alerts - `alerts_by_channel_type` object: Count of alerts by notification channel type ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `422`: Unprocessable Entity - `429`: Too Many Requests - `500`: Internal Server Error - `503`: Service Unavailable ## Changes - **2026-10-09** `61a175e8eb9a`: 2 warning, 5 info - removed the optional property `detail` from the response with the `422` status - added the new `ingest_stalled` enum value to the `results/items/system_condition/anyOf[subschema #1: SystemCondition]/type` response property for the response status `200` - added the non-success response with the status `429` - added the non-success response with the status `503` - …3 more - **2026-10-06** `b75474e978ff`: 3 warning - added the new `budget_threshold` enum value to the `results/items/system_condition/anyOf[subschema #1: SystemCondition]/type` response property for the response status `200` - added the new `collection_stale` enum value to the `results/items/system_condition/anyOf[subschema #1: SystemCondition]/type` response property for the response status `200` - added the new `retriever_no_interactions` enum value to the `results/items/system_condition/anyOf[subschema #1: SystemCondition]/type` response property for the response status `200` - **2026-10-04** `38e0822db900`: 6 info - added the optional property `results/items/cooldown_seconds` to the response with the `200` status - added the optional property `results/items/inputs` to the response with the `200` status - added the optional property `results/items/last_fired_at` to the response with the `200` status - added the optional property `results/items/min_count` to the response with the `200` status - …2 more - …earlier changes not shown [Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/organizations/alerts/list/post.md) --- [API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)