> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Alerts

> List all alerts in the namespace with optional filtering and pagination.

    **Filtering:**
    - Use `search` for wildcard text search across alert_id, name, description
    - Use `filters` for structured queries

    **Sorting:**
    - Default: created_at descending (newest first)



## OpenAPI

````yaml post /v1/alerts/list
openapi: 3.1.0
info:
  title: Mixpeek API
  description: >-
    This is the Mixpeek API, providing access to various endpoints for data
    processing and retrieval.
  termsOfService: https://mixpeek.com/terms
  contact:
    name: Mixpeek Support
    url: https://mixpeek.com/contact
    email: info@mixpeek.com
  version: '0.82'
servers:
  - url: https://api.mixpeek.com
    description: Production
security: []
paths:
  /v1/alerts/list:
    post:
      tags:
        - Alerts
      summary: List Alerts
      description: |-
        List all alerts in the namespace with optional filtering and pagination.

            **Filtering:**
            - Use `search` for wildcard text search across alert_id, name, description
            - Use `filters` for structured queries

            **Sorting:**
            - Default: created_at descending (newest first)
      operationId: list_alerts_v1_alerts_list_post
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 1000
                minimum: 1
              - type: 'null'
            title: Limit
        - name: page_size
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 1000
                minimum: 1
              - type: 'null'
            title: Page Size
        - name: offset
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 10000
                minimum: 0
              - type: 'null'
            title: Offset
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            title: Page
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
        - name: include_total
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include Total
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListAlertsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAlertsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ListAlertsRequest:
      properties:
        search:
          anyOf:
            - type: string
            - type: 'null'
          title: Search
          description: Search term for wildcard search across alert_id, name, description
        filters:
          anyOf:
            - $ref: '#/components/schemas/LogicalOperator-Input'
            - type: 'null'
          description: Filters to apply to the alert list
        sort:
          anyOf:
            - $ref: '#/components/schemas/SortOption'
            - type: 'null'
          description: Sort configuration for the alert list
        case_sensitive:
          type: boolean
          title: Case Sensitive
          description: If True, filters and search will be case-sensitive
          default: false
      type: object
      title: ListAlertsRequest
      description: Request model to list alerts.
    ListAlertsResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/AlertResponse'
          type: array
          title: Results
          description: List of alerts
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
          description: Pagination information
        total_count:
          type: integer
          title: Total Count
          description: Total number of alerts matching query
        stats:
          anyOf:
            - $ref: '#/components/schemas/AlertListStats'
            - type: 'null'
          description: Aggregate statistics across all alerts in the result
      type: object
      required:
        - results
        - pagination
        - total_count
      title: ListAlertsResponse
      description: Response model for listing alerts.
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        status:
          type: integer
          title: Status
          description: HTTP status code for this error
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: Error details payload
      type: object
      required:
        - status
        - error
      title: ErrorResponse
      description: Error response model.
      examples:
        - error:
            details:
              id: ns_123
              resource: namespace
            message: Namespace not found
            type: NotFoundError
          status: 404
          success: false
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LogicalOperator-Input:
      properties:
        AND:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/LogicalOperator-Input'
                  - $ref: '#/components/schemas/FilterCondition'
              type: array
            - type: 'null'
          title: And
          description: Logical AND operation - all conditions must be true
          example:
            - field: name
              operator: eq
              value: John
            - field: age
              operator: gte
              value: 30
        OR:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/LogicalOperator-Input'
                  - $ref: '#/components/schemas/FilterCondition'
              type: array
            - type: 'null'
          title: Or
          description: Logical OR operation - at least one condition must be true
          example:
            - field: status
              operator: eq
              value: active
            - field: role
              operator: eq
              value: admin
        NOT:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/LogicalOperator-Input'
                  - $ref: '#/components/schemas/FilterCondition'
              type: array
            - type: 'null'
          title: Not
          description: Logical NOT operation - all conditions must be false
          example:
            - field: department
              operator: eq
              value: HR
            - field: location
              operator: eq
              value: remote
        case_sensitive:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Case Sensitive
          description: Whether to perform case-sensitive matching
          default: false
          example: true
      additionalProperties: true
      type: object
      title: LogicalOperator
      description: >-
        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"}).
    SortOption:
      properties:
        field:
          type: string
          title: Field
          description: Field to sort by, supports dot notation for nested fields
          example: created_at
        direction:
          $ref: '#/components/schemas/SortDirection'
          description: Sort direction
          default: asc
          example: desc
      type: object
      required:
        - field
      title: SortOption
      description: |-
        Specifies how to sort query results.

        Attributes:
            field: Field to sort by
            direction: Sort direction (ascending or descending)
    AlertResponse:
      properties:
        alert_id:
          type: string
          title: Alert Id
          description: Unique identifier for the alert
          examples:
            - alt_abc123xyz789
        namespace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Namespace Id
          description: Namespace this alert belongs to
          examples:
            - ns_production
            - ns_staging
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
          description: Human-readable name for the alert
          examples:
            - Safety Incident Detector
            - Prohibited Content Alert
        description:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Description
          description: Optional description of what this alert monitors
          examples:
            - Alerts when new videos match known safety incidents
        source:
          $ref: '#/components/schemas/AlertSource'
          description: >-
            Trigger source: 'retriever' (runs a retriever) or 'system' (built-in
            metric)
          default: retriever
        retriever_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retriever Id
          description: >-
            ID of the retriever to execute (source=retriever only). The
            retriever defines filters, scoring, limits.
          examples:
            - ret_safety_search
            - ret_prohibited_content
        trigger_on:
          $ref: '#/components/schemas/TriggerOn'
          description: >-
            For source=retriever: fire on 'results' (matches found) or
            'no_results' (retriever went dark).
          default: results
        system_condition:
          anyOf:
            - $ref: '#/components/schemas/SystemCondition'
            - type: 'null'
          description: Built-in data-plane condition to watch (source=system only)
        namespace_selector:
          anyOf:
            - $ref: '#/components/schemas/NamespaceSelector'
            - type: 'null'
          description: >-
            Org-level namespace scoping (all vs selected). When omitted, the
            alert is scoped to its own namespace_id.
        notification_config:
          $ref: '#/components/schemas/AlertNotificationConfig'
          description: How and where to send notifications when alert triggers
        enabled:
          type: boolean
          title: Enabled
          description: Whether the alert is active and will execute
          default: true
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: Timestamp when the alert was created
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: Timestamp when the alert was last updated
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Additional user-defined metadata for the alert
      type: object
      required:
        - name
        - notification_config
      title: AlertResponse
      description: Response model for a single alert.
      examples:
        - alert_id: alt_safety_001
          description: Alerts when new videos match known safety incidents
          enabled: true
          name: Safety Incident Detector
          notification_config:
            channels:
              - channel_id: wh_safety_team
                channel_type: webhook
            include_matches: true
            include_scores: true
          retriever_id: ret_safety_search
    PaginationResponse:
      properties:
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
        page_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Size
        total_pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Pages
        next_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page
        previous_page:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Page
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      title: PaginationResponse
      description: |-
        PaginationResponse.

        Cursor-based pagination response:
        - Use next_cursor for navigation
        - Total count fields only populated when include_total=true
    AlertListStats:
      properties:
        total_alerts:
          type: integer
          title: Total Alerts
          description: Total number of alerts
          default: 0
        enabled_alerts:
          type: integer
          title: Enabled Alerts
          description: Number of enabled alerts
          default: 0
        disabled_alerts:
          type: integer
          title: Disabled Alerts
          description: Number of disabled alerts
          default: 0
        alerts_by_channel_type:
          additionalProperties:
            type: integer
          type: object
          title: Alerts By Channel Type
          description: Count of alerts by notification channel type
      type: object
      title: AlertListStats
      description: Aggregate statistics for a list of alerts.
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error message
        type:
          type: string
          title: Type
          description: Stable error type identifier (machine-readable)
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Fine-grained error code for programmatic handling (e.g.,
            namespace_name_taken, feature_extractor_not_found). Present only
            when consumers may need to branch on a specific error condition.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: >-
            Optional structured details to help debugging (validation errors,
            IDs, etc.)
      type: object
      required:
        - message
        - type
      title: ErrorDetail
      description: Error detail model.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    FilterCondition:
      properties:
        field:
          type: string
          title: Field
          description: Field name to filter on
        operator:
          $ref: '#/components/schemas/FilterOperator'
          description: Comparison operator
          default: eq
        value:
          anyOf:
            - $ref: '#/components/schemas/DynamicValue'
            - {}
          title: Value
          description: Value to compare against
      type: object
      required:
        - field
        - value
      title: FilterCondition
      description: |-
        Represents a single filter condition.

        Attributes:
            field: The field to filter on
            operator: The comparison operator
            value: The value to compare against
    SortDirection:
      type: string
      enum:
        - asc
        - desc
      title: SortDirection
      description: Sort direction options.
    AlertSource:
      type: string
      enum:
        - retriever
        - system
      title: AlertSource
      description: >-
        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.
    TriggerOn:
      type: string
      enum:
        - results
        - no_results
      title: TriggerOn
      description: >-
        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).
    SystemCondition:
      properties:
        type:
          $ref: '#/components/schemas/SystemConditionType'
          description: Which built-in data-plane condition to evaluate
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Per-condition threshold overrides (evaluator supplies defaults)
          examples:
            - stall_minutes: 30
            - error_rate_threshold: 0.1
      type: object
      required:
        - type
      title: SystemCondition
      description: >-
        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.
    NamespaceSelector:
      properties:
        mode:
          $ref: '#/components/schemas/NamespaceSelectorMode'
          description: Whether the alert applies to all namespaces or a selected set
          default: all
        namespace_ids:
          items:
            type: string
          type: array
          title: Namespace Ids
          description: Namespace IDs the alert applies to (when mode=selected)
          examples:
            - - ns_production
              - ns_staging
      type: object
      title: NamespaceSelector
      description: |-
        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.
    AlertNotificationConfig:
      properties:
        channels:
          items:
            $ref: '#/components/schemas/NotificationChannelConfig'
          type: array
          minItems: 1
          title: Channels
          description: List of notification channels to send alerts to
        include_matches:
          type: boolean
          title: Include Matches
          description: Include matched documents in notification payload
          default: true
        include_scores:
          type: boolean
          title: Include Scores
          description: Include similarity scores in notification payload
          default: true
        template_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Template Id
          description: Optional notification template for formatting
      type: object
      required:
        - channels
      title: AlertNotificationConfig
      description: |-
        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
      examples:
        - channels:
            - channel_id: wh_safety_team
              channel_type: webhook
            - channel_id: sl_alerts
              channel_type: slack
          include_matches: true
          include_scores: true
    FilterOperator:
      type: string
      enum:
        - eq
        - ne
        - gt
        - lt
        - gte
        - lte
        - in
        - nin
        - contains
        - starts_with
        - ends_with
        - regex
        - exists
        - is_null
        - text
        - phrase
      title: FilterOperator
      description: Supported filter operators across database implementations.
    DynamicValue:
      properties:
        type:
          type: string
          const: dynamic
          title: Type
          default: dynamic
        field:
          type: string
          title: Field
          description: >-
            The dot-notation path to the value in the runtime query request,
            e.g., 'inputs.user_id'
          examples:
            - inputs.query_text
            - filters.AND[0].value
      type: object
      required:
        - field
      title: DynamicValue
      description: A value that should be dynamically resolved from the query request.
    SystemConditionType:
      type: string
      enum:
        - collection_empty
        - batch_failed
        - batch_stalled
        - retriever_latency
        - retriever_no_results
        - batch_error_rate
        - collection_drift
        - retriever_accuracy
        - retriever_alignment_regression
      title: SystemConditionType
      description: Built-in data-plane conditions a system-source alert can watch.
    NamespaceSelectorMode:
      type: string
      enum:
        - all
        - selected
      title: NamespaceSelectorMode
      description: How an org-level alert chooses which namespaces it applies to.
    NotificationChannelConfig:
      properties:
        channel_type:
          type: string
          title: Channel Type
          description: 'Type of notification channel: ''webhook'', ''slack'', ''email'''
          examples:
            - webhook
            - slack
            - email
        channel_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Channel Id
          description: >-
            Reference to a pre-configured notification channel in the
            organization
          examples:
            - wh_safety_team
            - sl_alerts
            - em_security
        config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Config
          description: >-
            Channel-specific configuration overrides (e.g., webhook URL, Slack
            channel)
          examples:
            - url: https://example.com/webhook
            - channel: '#alerts'
            - to:
                - admin@example.com
      type: object
      required:
        - channel_type
      title: NotificationChannelConfig
      description: |-
        Configuration for a notification channel.

        Channels define where notifications are sent when an alert is triggered.
        Supports multiple channel types including webhooks, Slack, and email.

        Attributes:
            channel_type: Type of notification channel (webhook, slack, email)
            channel_id: Optional reference to a pre-configured channel in the organization
            config: Optional channel-specific configuration overrides

````