---
title: "List Alerts (GET alias for POST /list)."
method: GET
path: "/v1/alerts"
tags: ["Alerts"]
---

# List Alerts (GET alias for POST /list).

`GET /v1/alerts`

List alerts with pagination and filtering.

## 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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `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).
    - `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', 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 notification channel: 'webhook', 'slack', 'email'
        - `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)
      - `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
    - `page` integer, nullable
    - `page_size` integer, nullable
    - `total_pages` integer, nullable
    - `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` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)