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

# Preview monitor content-filter matches

> Read-only preview for a CANDIDATE monitor config: how many and which recent past sessions the given content filter, message conditions and sampling percentage would select, among the most recent closed production sessions inside a look-back window. Runs no evaluations, spends no credits, and writes nothing (no processed marks). Use it while creating or editing a monitor. The match count is exact; for a create preview (no `monitorId`) the sampled subset is representative, not the exact set the created monitor will draw. With `metricGroupIds` or `specificationIds`, it also answers the credits one evaluated session costs.

> [!WARNING]
>
> You are reading the docs of Galtea 5.14. [Read this page in the latest version](https://docs.galtea.ai/api-reference/monitors/preview-monitor-content-filter-matches.md).


## OpenAPI

````yaml /v5.14/openapi.json post /monitors/preview
openapi: 3.0.0
info:
  version: 1.0.0
  title: Product Management Service API
  description: API documentation for Product Management Service
  contact:
    name: Galtea AI
servers:
  - url: https://api.galtea.ai
security:
  - bearerAuth: []
tags: []
externalDocs:
  description: Galtea Platform Documentation
  url: https://docs.galtea.ai
paths:
  /monitors/preview:
    post:
      tags:
        - monitors
      summary: Preview monitor content-filter matches
      description: >-
        Read-only preview for a CANDIDATE monitor config: how many and which
        recent past sessions the given content filter, message conditions and
        sampling percentage would select, among the most recent closed
        production sessions inside a look-back window. Runs no evaluations,
        spends no credits, and writes nothing (no processed marks). Use it while
        creating or editing a monitor. The match count is exact; for a create
        preview (no `monitorId`) the sampled subset is representative, not the
        exact set the created monitor will draw. With `metricGroupIds` or
        `specificationIds`, it also answers the credits one evaluated session
        costs.
      operationId: previewMonitorMatches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewMonitorMatchesRequest'
      responses:
        '200':
          description: Preview computed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorMatchPreview'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The caller cannot create monitors for this product. A product in
            another organization also yields 403 (not 404), so the endpoint
            never leaks whether a foreign product exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            No product exists with the given id (a product in another
            organization yields 403, not 404)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    PreviewMonitorMatchesRequest:
      type: object
      properties:
        productId:
          type: string
          minLength: 1
          example: prod_123
          description: Product whose recent production sessions the preview scans.
        versionId:
          type: string
          nullable: true
          description: >-
            Optional version to narrow the preview to. Null previews the whole
            product.
          example: version_123
        filterQuery:
          type: string
          nullable: true
          maxLength: 500
          description: >-
            Candidate content filter. Null keeps every session that meets the
            message conditions.
          example: refund
        filterTarget:
          type: string
          nullable: true
          enum:
            - INPUT
            - OUTPUT
            - EITHER
            - null
          description: >-
            Which side of a turn filterQuery matches against. Set together with
            filterQuery.
          example: EITHER
        excludeQuery:
          type: string
          nullable: true
          maxLength: 500
          description: >-
            Candidate exclude filter. Comma-separated terms; a session is
            dropped when a turn whose chosen target (excludeTarget) contains ANY
            term. Null excludes nothing. Set together with excludeTarget.
            Independent of filterQuery.
          example: test, internal
        excludeTarget:
          type: string
          nullable: true
          enum:
            - INPUT
            - OUTPUT
            - EITHER
            - null
          description: >-
            Which side of a turn excludeQuery matches against. Set together with
            excludeQuery.
          example: EITHER
        messageConditions:
          type: array
          items:
            $ref: '#/components/schemas/MonitorMessageCondition'
          maxItems: 10
          description: >-
            Candidate message conditions, joined by AND. Omitted previews the
            default (messages above 1); [] previews no message filter. A list no
            session can meet is refused, such as messages above 5 with messages
            at most 3, or more user messages than the messages allow: `messages`
            counts the user messages too.
          example:
            - count: messages
              operator: gt
              value: 1
        samplingPercentage:
          type: number
          minimum: 0
          exclusiveMinimum: true
          maximum: 100
          description: Candidate sampling percentage (greater than 0, at most 100).
          example: 10
        days:
          type: integer
          minimum: 1
          maximum: 90
          default: 90
          description: >-
            Look-back window in days that bounds which sessions are read
            (default 90, max 90).
          example: 90
        monitorId:
          type: string
          nullable: true
          description: >-
            Existing monitor id when previewing an EDIT, so sampling uses its
            real seed (exact). Omit for a create preview (representative
            sampling).
          example: monitor_123
        metricGroupIds:
          type: array
          items:
            type: string
          description: >-
            The metric families picked on the candidate monitor, as on create.
            Set it or specificationIds to receive creditsPerSession; omit both
            when you do not need the cost. A family that has no current metric,
            or whose metrics belong to another organization, counts 0.
          example:
            - metricGroup_123
        specificationIds:
          type: array
          items:
            type: string
          description: >-
            The Specifications bound to the candidate monitor, as on create. The
            cost counts each family they bring that can score production
            sessions, and a family that is also in metricGroupIds once.
          example:
            - specification_123
      required:
        - productId
        - samplingPercentage
    MonitorMatchPreview:
      type: object
      properties:
        range:
          type: object
          properties:
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
          required:
            - from
            - to
          description: The requested look-back window.
        candidateCount:
          type: integer
          description: >-
            Recent closed production sessions considered (bounded by the window
            and an internal cap).
          example: 500
        readRange:
          type: object
          nullable: true
          properties:
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
          required:
            - from
            - to
          description: >-
            Oldest and newest creation time of the sessions actually read. Null
            when no session was read.
        candidateLimit:
          type: integer
          description: The most sessions the preview reads.
          example: 500
        candidateLimitReached:
          type: boolean
          description: >-
            True when the preview read `candidateLimit` sessions, so older
            sessions inside the window were not read.
          example: false
        withTurnsCount:
          type: integer
          description: >-
            Sessions read that hold at least one turn. The scanner never
            evaluates a session with no turn.
          example: 480
        contentFilterMatchCount:
          type: integer
          description: >-
            Sessions with at least one turn whose content filter passes. Equals
            `withTurnsCount` when no content filter is set.
          example: 150
        matchCount:
          type: integer
          description: >-
            Sessions that met the message conditions and matched the candidate
            filter (exact; a null filter keeps every session that meets the
            message conditions).
          example: 120
        sampledCount:
          type: integer
          description: Matched sessions that also fell in the sampling fraction.
          example: 12
        approximateSampling:
          type: boolean
          description: >-
            True for a create preview (no monitorId): the sampled subset is
            representative, computed from a placeholder seed. The match count is
            always exact.
          example: true
        creditsPerSession:
          type: integer
          nullable: true
          description: >-
            Credits that scoring one evaluated session costs, at the current
            price, for the families metricGroupIds and specificationIds give, as
            the scanner charges them. A metric that costs nothing (Self-Hosted,
            Human Evaluation, or disabled) counts 0, so empty lists cost 0. Null
            when the request omits both metricGroupIds and specificationIds.
          example: 4
        sampledSessions:
          type: array
          items:
            type: object
            properties:
              sessionId:
                type: string
                example: session_123
              versionId:
                type: string
                example: version_123
              createdAt:
                type: string
                format: date-time
              turnCount:
                type: integer
                example: 4
              matchedText:
                type: string
                description: >-
                  A short snippet of the matched content (centered on the first
                  matched term with a content filter) or the first turn input
                  (without a filter). Capped at ~160 characters plus ellipsis
                  markers.
                example: >-
                  I would like a refund for my last order because it arrived
                  damaged…
            required:
              - sessionId
              - versionId
              - createdAt
              - turnCount
              - matchedText
          description: The would-be-selected sessions, most-recent first (capped at 100).
      required:
        - range
        - candidateCount
        - readRange
        - candidateLimit
        - candidateLimitReached
        - withTurnsCount
        - contentFilterMatchCount
        - matchCount
        - sampledCount
        - approximateSampling
        - creditsPerSession
        - sampledSessions
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error type
        message:
          type: string
          example: Error message description
    MonitorMessageCondition:
      type: object
      properties:
        count:
          type: string
          enum:
            - messages
            - user_messages
          description: >-
            `messages` counts each non-empty turn input and each non-empty turn
            output; `user_messages` counts non-empty turn inputs only. An input
            of `{}`, `{"user_message": null}` or `{"user_message": ""}` and an
            output of `{}`, `{"assistant_message": null}` or
            `{"assistant_message": ""}` count as empty. A blank `user_message`
            or `assistant_message` beside another key counts.
          example: messages
        operator:
          type: string
          enum:
            - lt
            - lte
            - eq
            - gte
            - gt
          description: lt, lte, eq, gte, gt.
          example: gt
        value:
          type: integer
          minimum: 0
          maximum: 200
          example: 1
      required:
        - count
        - operator
        - value
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authorization. Pass your API key in the Authorization header as
        a Bearer token. Both new (`gsk_*`) and legacy (`gsk-`) API keys are
        accepted, e.g. `Authorization: Bearer gsk_...` or `Authorization: Bearer
        gsk-...`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.