> ## 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.

# Create monitor

> Create a new monitor. It scores the metric families in metricGroupIds and the metrics of the Specifications in specificationIds; at least one of the two is required. See [Monitors](https://docs.galtea.ai/concepts/product/monitor).

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


## OpenAPI

````yaml /v5.11/openapi.json post /monitors
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:
    post:
      tags:
        - monitors
      summary: Create monitor
      description: >-
        Create a new monitor. It scores the metric families in metricGroupIds
        and the metrics of the Specifications in specificationIds; at least one
        of the two is required. See
        [Monitors](https://docs.galtea.ai/concepts/product/monitor).
      operationId: createMonitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMonitorRequest'
      responses:
        '201':
          description: >-
            Monitor created successfully. The Location header holds its path.
            The body holds only the monitor id when the read after the write
            fails; read the monitor by that id.
          headers:
            Location:
              schema:
                type: string
                description: The path of the new monitor
              required: true
              description: The path of the new monitor
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/Monitor'
                  - $ref: '#/components/schemas/MonitorId'
        '400':
          description: >-
            Invalid request body, including a metric family with no active head,
            a self-hosted metric family (a monitor has no score to record for
            it), an Inability Specification, a Specification of another product,
            a name another monitor of the product already uses, or a scope that
            no metric can score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateMonitorRequest:
      type: object
      properties:
        productId:
          type: string
          minLength: 1
          example: prod_123
        versionId:
          type: string
          nullable: true
          description: >-
            Optional version to narrow the monitor to. When null the monitor
            watches the whole product.
          example: version_123
        name:
          type: string
          example: Production quality watch
        metricGroupIds:
          type: array
          items:
            type: string
          description: >-
            The metric families (Metric.metricGroupId) picked directly on the
            monitor. The list may be empty when specificationIds is set. The
            families the monitor scores are in scoredMetricGroupIds. The monitor
            binds the family, not a specific revision, so revising a metric is
            picked up automatically without editing the monitor.
          example:
            - metricGroup_123
        specificationIds:
          type: array
          items:
            type: string
          description: >-
            The Specifications (Specification.id) bound to the monitor. The
            monitor also scores the metrics each one links, so a metric added to
            or removed from a Specification takes effect on the next scan. Only
            Policy and Capability Specifications can be bound. At least one of
            metricGroupIds and specificationIds is required.
          example:
            - specification_123
        samplingPercentage:
          type: number
          default: 10
          minimum: 0
          exclusiveMinimum: true
          maximum: 100
          description: >-
            Percentage of production sessions to evaluate (greater than 0, at
            most 100).
          example: 10
        monthlyCreditCap:
          type: integer
          nullable: true
          minimum: 1
          description: >-
            Optional monthly credit ceiling for this monitor. When set it must
            be a positive integer; it may exceed the organization monthly
            allocation (spend is clamped to the available balance). Null means
            uncapped.
          example: 500
        filterQuery:
          type: string
          nullable: true
          maxLength: 500
          description: >-
            Optional content gate. Comma-separated terms; a session matches when
            at least one turn whose chosen target (filterTarget) contains ANY
            term (case-insensitive). Only matching sessions are sampled and
            evaluated; other sessions are skipped, spending no credits. Max 500
            chars. Must be set together with filterTarget. Null means watch
            every session.
          example: refund, cancel, chargeback
        filterTarget:
          type: string
          nullable: true
          enum:
            - INPUT
            - OUTPUT
            - EITHER
            - null
          description: >-
            Which side of a turn filterQuery is matched against: INPUT (the user
            turn), OUTPUT (the agent turn), or EITHER. Must be set together with
            filterQuery.
          example: EITHER
        excludeQuery:
          type: string
          nullable: true
          maxLength: 500
          description: >-
            Optional exclude gate. Comma-separated terms; a session is dropped
            when at least one turn whose chosen target (excludeTarget) contains
            ANY term (case-insensitive). Applied on top of filterQuery: a
            session is watched only when it passes filterQuery (if set) AND is
            not hit by excludeQuery. Max 500 chars. Must be set together with
            excludeTarget. Null means exclude nothing.
          example: test, internal
        excludeTarget:
          type: string
          nullable: true
          enum:
            - INPUT
            - OUTPUT
            - EITHER
            - null
          description: >-
            Which side of a turn excludeQuery is matched against: INPUT (the
            user turn), OUTPUT (the agent turn), or EITHER. Must be set together
            with excludeQuery.
          example: EITHER
        status:
          type: string
          enum:
            - ACTIVE
            - PAUSED
            - CAPPED
            - NO_CREDITS
            - FAILING
          default: ACTIVE
          description: >-
            Users may set ACTIVE or PAUSED; CAPPED and NO_CREDITS are system-set
            by the scanner, FAILING is reserved and never set yet, and all three
            are rejected on user writes.
          example: ACTIVE
      required:
        - productId
        - name
    Monitor:
      type: object
      properties:
        id:
          type: string
          example: monitor_123
        productId:
          type: string
          example: prod_123
        versionId:
          type: string
          nullable: true
          description: >-
            Optional version to narrow the monitor to. When null the monitor
            watches the whole product.
          example: version_123
        userId:
          type: string
          nullable: true
          example: user_123
        name:
          type: string
          example: Production quality watch
        metricGroupIds:
          type: array
          items:
            type: string
          description: >-
            The metric families (Metric.metricGroupId) picked directly on the
            monitor. The list may be empty when specificationIds is set. The
            families the monitor scores are in scoredMetricGroupIds. The monitor
            binds the family, not a specific revision, so revising a metric is
            picked up automatically without editing the monitor.
          example:
            - metricGroup_123
        specificationIds:
          type: array
          items:
            type: string
          description: >-
            The Specifications (Specification.id) bound to the monitor. The
            monitor also scores the metrics each one links, so a metric added to
            or removed from a Specification takes effect on the next scan. Only
            Policy and Capability Specifications can be bound.
          example:
            - specification_123
        scoredMetricGroupIds:
          type: array
          items:
            type: string
          description: >-
            Read-only. The metric families the monitor scores: metricGroupIds
            plus the families of its bound Specifications that can score
            production sessions.
          example:
            - metricGroup_123
        specificationIdsByMetricGroupId:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Read-only. For each family a bound Specification brings, the ids of
            the bound Specifications that bring it.
          example:
            metricGroup_123:
              - specification_123
        samplingPercentage:
          type: number
          default: 10
          minimum: 0
          exclusiveMinimum: true
          maximum: 100
          description: >-
            Percentage of production sessions to evaluate (greater than 0, at
            most 100).
          example: 10
        monthlyCreditCap:
          type: integer
          nullable: true
          minimum: 1
          description: >-
            Optional monthly credit ceiling for this monitor. When set it must
            be a positive integer; it may exceed the organization monthly
            allocation (spend is clamped to the available balance). Null means
            uncapped.
          example: 500
        filterQuery:
          type: string
          nullable: true
          maxLength: 500
          description: >-
            Optional content gate. Comma-separated terms; a session matches when
            at least one turn whose chosen target (filterTarget) contains ANY
            term (case-insensitive). Only matching sessions are sampled and
            evaluated; other sessions are skipped, spending no credits. Max 500
            chars. Must be set together with filterTarget. Null means watch
            every session.
          example: refund, cancel, chargeback
        filterTarget:
          type: string
          nullable: true
          enum:
            - INPUT
            - OUTPUT
            - EITHER
            - null
          description: >-
            Which side of a turn filterQuery is matched against: INPUT (the user
            turn), OUTPUT (the agent turn), or EITHER. Must be set together with
            filterQuery.
          example: EITHER
        excludeQuery:
          type: string
          nullable: true
          maxLength: 500
          description: >-
            Optional exclude gate. Comma-separated terms; a session is dropped
            when at least one turn whose chosen target (excludeTarget) contains
            ANY term (case-insensitive). Applied on top of filterQuery: a
            session is watched only when it passes filterQuery (if set) AND is
            not hit by excludeQuery. Max 500 chars. Must be set together with
            excludeTarget. Null means exclude nothing.
          example: test, internal
        excludeTarget:
          type: string
          nullable: true
          enum:
            - INPUT
            - OUTPUT
            - EITHER
            - null
          description: >-
            Which side of a turn excludeQuery is matched against: INPUT (the
            user turn), OUTPUT (the agent turn), or EITHER. Must be set together
            with excludeQuery.
          example: EITHER
        status:
          type: string
          enum:
            - ACTIVE
            - PAUSED
            - CAPPED
            - NO_CREDITS
            - FAILING
          default: ACTIVE
          description: >-
            Users may set ACTIVE or PAUSED; CAPPED and NO_CREDITS are system-set
            by the scanner, FAILING is reserved and never set yet, and all three
            are rejected on user writes.
          example: ACTIVE
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - productId
        - versionId
        - userId
        - name
        - metricGroupIds
        - specificationIds
        - scoredMetricGroupIds
        - specificationIdsByMetricGroupId
        - samplingPercentage
        - monthlyCreditCap
        - filterQuery
        - filterTarget
        - excludeQuery
        - excludeTarget
        - status
        - createdAt
        - deletedAt
    MonitorId:
      type: object
      properties:
        id:
          type: string
          example: monitor_123
      required:
        - id
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error type
        message:
          type: string
          example: Error message description
  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.