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

# Get metrics

> Get list of metrics with pagination and filtering. See [Metrics](https://docs.galtea.ai/concepts/metric).

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


## OpenAPI

````yaml /v5.19/openapi.json get /metrics
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:
  /metrics:
    get:
      tags:
        - metrics
      summary: Get metrics
      description: >-
        Get list of metrics with pagination and filtering. See
        [Metrics](https://docs.galtea.ai/concepts/metric).
      operationId: getMetrics
      parameters:
        - name: ids
          in: query
          style: form
          explode: true
          description: Filter by metric IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: metricGroupIds
          in: query
          style: form
          explode: true
          description: >-
            Filter by metric family IDs (Revision.metricGroupId). Returns every
            revision of the family, legacy ones included.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: organizationIds
          in: query
          style: form
          explode: true
          description: Filter by organization IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: productIds
          in: query
          style: form
          explode: true
          description: Filter by product IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: names
          in: query
          style: form
          explode: true
          description: >-
            Filter by metric names (exact match, case insensitive, multiple). A
            name no visible metric has then matches the active revisions whose
            own name it is, or every such revision with includeLegacy. A
            response shows a revision's own name when it has one, so a lookup by
            a metric's name can answer another name. Names change; prefer ids.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: name
          in: query
          description: >-
            Filter by metric name (partial match, case insensitive). When no
            visible metric name contains it, it matches the own names of the
            active revisions instead, or of every revision with includeLegacy.
          required: false
          schema:
            type: string
        - name: description
          in: query
          description: Filter by metric description (partial match)
          required: false
          schema:
            type: string
        - name: tags
          in: query
          style: form
          explode: true
          description: Filter by tags
          required: false
          schema:
            type: array
            items:
              type: string
        - name: sources
          in: query
          style: form
          explode: true
          description: Filter by metric sources
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - SELF_HOSTED
                - FULL_PROMPT
                - PARTIAL_PROMPT
                - HUMAN_EVALUATION
                - GEVAL
                - DEEPEVAL
                - DETERMINISTIC
                - CLASSIFIER
        - name: specificationIds
          in: query
          style: form
          explode: true
          description: Filter by specification IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: userGroupIds
          in: query
          style: form
          explode: true
          description: Filter by user group IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: fromCreatedAt
          in: query
          description: Filter metrics created at or after this timestamp (ISO 8601 format)
          required: false
          schema:
            type: string
            format: date-time
        - name: toCreatedAt
          in: query
          description: Filter metrics created at or before this timestamp (ISO 8601 format)
          required: false
          schema:
            type: string
            format: date-time
        - name: includeDefaultEntities
          in: query
          description: Include default/predefined metrics
          required: false
          schema:
            type: boolean
        - name: includeOwnEntities
          in: query
          description: Include metrics owned by the user's organization
          required: false
          schema:
            type: boolean
        - name: includeLegacy
          in: query
          description: >-
            Include legacy/deprecated metrics. Also includes an optimization
            candidate waiting for review, which is legacy until it is activated.
          required: false
          schema:
            type: boolean
        - name: includeExcludedFromAnalytics
          in: query
          description: Include metric revisions that are excluded from analytics
          required: false
          schema:
            type: boolean
        - name: suitableForMonitoring
          in: query
          description: Filter metrics suitable for monitoring
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          style: form
          explode: true
          description: Sort instructions (field and direction pairs)
          required: false
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          description: Maximum number of results
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: Number of results to skip
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Metrics retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Metric'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            A requested id names another organization's metric or a metric that
            none of the products the caller's user groups grant uses, or a
            requested product or specification is outside those products. Also
            answered when no user group of the caller lists metric.read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            A name in `names` is ambiguous. No visible metric has it, and more
            than one active revision has it as its own name. Use the metric id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Metric:
      type: object
      properties:
        id:
          type: string
          example: metric_123
        metricGroupId:
          type: string
          readOnly: true
          example: metric_123
          description: >-
            Identifier shared by every metric in the same revision family.
            Server-managed — derived from `parentMetricId` on create (or
            generated for roots). Cannot be set by the caller.
        parentMetricId:
          type: string
          nullable: true
          example: metric_122
          description: >-
            Id of the direct parent metric. On create, providing this value
            turns the new metric into a revision: it joins the parent's family
            and becomes its only active revision: the family's current active
            revision becomes legacy, whether it is the parent or not. Omit or
            null to create a root metric in a fresh group. On responses, this is
            the recorded parent edge (null for roots).
        organizationId:
          type: string
          nullable: true
          example: org_123
        userId:
          type: string
          nullable: true
          example: user_123
        name:
          type: string
          example: Accuracy
          description: >-
            The revision's own name when it has one, else its metric's name. A
            lookup by a metric's name can answer a revision with its own name.
        evaluationParams:
          type: array
          items:
            type: string
          example:
            - input
            - actual_output
            - expected_output
          description: >-
            Ordered list of trace fields the evaluator needs, written in
            snake_case (e.g. `input`, `actual_output`, `expected_output`,
            `retrieval_context`). Determines which data the evaluation engine
            extracts from each trace. Full list of accepted values:
            https://docs.galtea.ai/concepts/metric/evaluation-parameters
        source:
          type: string
          nullable: true
          enum:
            - SELF_HOSTED
            - FULL_PROMPT
            - PARTIAL_PROMPT
            - HUMAN_EVALUATION
            - GEVAL
            - DEEPEVAL
            - DETERMINISTIC
            - CLASSIFIER
          example: PARTIAL_PROMPT
          description: >-
            Evaluation method for the metric. `FULL_PROMPT` is deprecated for
            creation — `POST /metrics` rejects it with a 400. Use
            `PARTIAL_PROMPT` for new AI Evaluation metrics. The value remains in
            the enum because existing FULL_PROMPT metrics are still returned by
            reads and filters. `CLASSIFIER` is the Classifier judge, accepted
            only where the deployment enables it.
        definition:
          type: string
          nullable: true
          description: >-
            Name of the built-in evaluator the metric runs, for example
            `json_field_match`. Null when the metric names none.
        judgePrompt:
          type: string
          nullable: true
          example: Evaluate the accuracy of the response
        tags:
          type: array
          items:
            type: string
          example:
            - accuracy
            - quality
        description:
          type: string
          nullable: true
          example: Measures the accuracy of responses
        documentationUrl:
          type: string
          nullable: true
          example: https://docs.example.com/metrics/accuracy
        evaluatorModelName:
          type: string
          nullable: true
          example: gpt-4
        areEvalParamsTop:
          type: boolean
          nullable: true
          description: >-
            When true, evaluationParams are injected at the top level of the
            evaluator prompt instead of nested inside the conversation context.
        isBeingOptimized:
          type: boolean
          readOnly: true
          description: Whether the metric is currently being optimized.
        optimizationStatus:
          type: string
          nullable: true
          enum:
            - OPTIMIZING
            - READY_FOR_REVIEW
            - FAILED
            - NO_IMPROVEMENT
            - DECLINED
            - ACTIVATED
          readOnly: true
          example: READY_FOR_REVIEW
          description: >-
            Where an optimization attempt stands. Null for a metric that did not
            come from an optimization. A candidate waiting for review is legacy
            until it is activated.
        judgeGenerationSettings:
          type: object
          nullable: true
          properties:
            temperature:
              type: number
              nullable: true
              minimum: 0
              example: 0.3
            topP:
              type: number
              nullable: true
              minimum: 0
              maximum: 1
              example: 0.9
            maxOutputTokens:
              type: integer
              nullable: true
              minimum: 1
              example: 512
              description: >-
                A new metric needs at least 256, so the judge's structured
                answer fits. A metric stored before that floor keeps its cap.
            reasoningEffort:
              type: string
              nullable: true
              example: low
          additionalProperties: false
          description: >-
            The generation settings this metric's judge runs with. Null runs the
            platform defaults. Immutable: changing one creates a revision.
        passThreshold:
          type: number
          minimum: 0
          maximum: 1
          example: 0.7
          description: >-
            Score from 0 to 1 at or above which an evaluation of this metric
            passes. Immutable: changing it creates a revision.
        applicabilityScope:
          type: string
          enum:
            - NONE
            - DEVELOPMENT
            - PRODUCTION
            - ALL
          example: PRODUCTION
          description: >-
            Which sessions get the applicability check before this metric is
            judged. `NONE` for a metric the platform does not score. A metric
            that scores only `traces` is never checked, so it takes `NONE` and
            refuses any other value. A metric that also scores another field is
            checked without `traces`: on each turn's input and actual output and
            its other fields. A FULL_PROMPT metric with empty evaluationParams
            whose judge prompt reads only `traces` is stored as checked, yet the
            evaluator judges it without the check. A FULL_PROMPT metric whose
            evaluationParams list only `traces` takes NONE even when its judge
            prompt reads another field: list that field in evaluationParams to
            get the check. Immutable: changing it creates a revision. The check
            runs only where the deployment enables it.
        applicabilityThreshold:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          example: 0.7
          description: >-
            The lowest probability that the metric applies to a session at which
            it is judged. Null means the platform default, 0.5. Immutable:
            changing it creates a revision.
        classifierQuestion:
          allOf:
            - $ref: '#/components/schemas/ClassifierQuestion'
            - nullable: true
              description: >-
                The one question of a CLASSIFIER metric; null for every other
                source.
        optimizationValidation:
          type: object
          nullable: true
          properties:
            used:
              type: boolean
              description: >-
                Whether any evaluation was held out for validation. False when
                none was: too few annotated evaluations and no session kept from
                an earlier attempt, or no session was eligible for the hold-out.
            heldOutEvaluationIds:
              type: array
              items:
                type: string
              description: >-
                Evaluations held out of the search. Empty when no validation set
                was used.
              example:
                - evaluation_123
            results:
              type: object
              nullable: true
              properties:
                optimization:
                  type: object
                  properties:
                    rowsScored:
                      type: integer
                      minimum: 0
                      description: Rows both prompts scored. Only these rows are compared.
                      example: 25
                    rowsTotal:
                      type: integer
                      minimum: 0
                      description: Rows in the set.
                      example: 25
                    source:
                      type: object
                      properties:
                        correct:
                          type: integer
                          minimum: 0
                          description: >-
                            Rows where the AI verdict matches the human label. A
                            score at or above the metric's pass threshold is a
                            positive verdict.
                          example: 20
                        alignment:
                          type: number
                          nullable: true
                          description: >-
                            Alignment between the AI scores and the human labels
                            on the compared rows. Null when undefined.
                          example: 0.71
                      required:
                        - correct
                        - alignment
                      additionalProperties: false
                    candidate:
                      type: object
                      properties:
                        correct:
                          type: integer
                          minimum: 0
                          description: >-
                            Rows where the AI verdict matches the human label. A
                            score at or above the metric's pass threshold is a
                            positive verdict.
                          example: 20
                        alignment:
                          type: number
                          nullable: true
                          description: >-
                            Alignment between the AI scores and the human labels
                            on the compared rows. Null when undefined.
                          example: 0.71
                      required:
                        - correct
                        - alignment
                      additionalProperties: false
                  required:
                    - rowsScored
                    - rowsTotal
                    - source
                    - candidate
                  additionalProperties: false
                validation:
                  type: object
                  properties:
                    rowsScored:
                      type: integer
                      minimum: 0
                      description: Rows both prompts scored. Only these rows are compared.
                      example: 25
                    rowsTotal:
                      type: integer
                      minimum: 0
                      description: Rows in the set.
                      example: 25
                    source:
                      type: object
                      properties:
                        correct:
                          type: integer
                          minimum: 0
                          description: >-
                            Rows where the AI verdict matches the human label. A
                            score at or above the metric's pass threshold is a
                            positive verdict.
                          example: 20
                        alignment:
                          type: number
                          nullable: true
                          description: >-
                            Alignment between the AI scores and the human labels
                            on the compared rows. Null when undefined.
                          example: 0.71
                      required:
                        - correct
                        - alignment
                      additionalProperties: false
                    candidate:
                      type: object
                      properties:
                        correct:
                          type: integer
                          minimum: 0
                          description: >-
                            Rows where the AI verdict matches the human label. A
                            score at or above the metric's pass threshold is a
                            positive verdict.
                          example: 20
                        alignment:
                          type: number
                          nullable: true
                          description: >-
                            Alignment between the AI scores and the human labels
                            on the compared rows. Null when undefined.
                          example: 0.71
                      required:
                        - correct
                        - alignment
                      additionalProperties: false
                  required:
                    - rowsScored
                    - rowsTotal
                    - source
                    - candidate
                  additionalProperties: false
              required:
                - optimization
                - validation
              additionalProperties: false
              description: >-
                Both prompts scored on the rows the search used and on the
                held-out rows. Null when the optimizer reported nothing.
            rows:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  evaluationId:
                    type: string
                    example: evaluation_123
                  humanScore:
                    type: number
                    description: The human label.
                    example: 1
                  sourceScore:
                    type: number
                    nullable: true
                    description: >-
                      The source prompt's judge score on this row, or null when
                      it failed. A score at or above the metric's pass threshold
                      is a positive verdict.
                    example: 0
                  candidateScore:
                    type: number
                    nullable: true
                    description: >-
                      The optimized prompt's judge score on this row, or null
                      when it failed. A score at or above the metric's pass
                      threshold is a positive verdict.
                    example: 1
                required:
                  - evaluationId
                  - humanScore
                  - sourceScore
                  - candidateScore
                additionalProperties: false
              description: >-
                One entry per held-out row the optimizer reported; a score is
                null when that prompt failed on the row. Null when the optimizer
                reported nothing.
          required:
            - used
            - heldOutEvaluationIds
            - results
            - rows
          additionalProperties: false
          readOnly: true
          description: >-
            How an optimization attempt was validated: the held-out evaluations
            and, once the optimizer reported, both prompts scored on the search
            rows and on the held-out rows. Set on an optimization attempt only,
            and null for any other metric, for an attempt that predates it, and
            for an attempt copied from another organization.
        optimizationRun:
          type: object
          nullable: true
          properties:
            strategies:
              type: array
              items:
                type: string
                enum:
                  - FIX_FALSE_POSITIVES
                  - FIX_FALSE_NEGATIVES
                  - ADD_RUBRIC
                  - SIMPLIFY
                  - BROADEN
              description: The strategies the run wrote candidates with.
              example:
                - ADD_RUBRIC
                - SIMPLIFY
            maxSteps:
              type: integer
              minimum: 1
              description: >-
                The run's step budget, after the optimizer applied its own
                ceiling.
              example: 6
            stepsUsed:
              type: integer
              minimum: 0
              description: >-
                The search steps the run took. 0 when the source prompt already
                met the target.
              example: 4
          required:
            - strategies
            - maxSteps
            - stepsUsed
          additionalProperties: false
          readOnly: true
          description: >-
            What an optimization attempt ran: the strategies, the step budget
            and the steps used. Null while the attempt runs, and when it was not
            reported: an attempt from before the report existed, one run by an
            older optimizer, a failed run, an attempt copied from another
            organization, or a metric that is not an optimization attempt. Null
            never means a run of 0 steps.
        specificationIds:
          type: array
          items:
            type: string
          description: >-
            Specifications linked to this metric. A MEMBER caller sees only the
            specifications of the products it can read.
          example:
            - spec_123
        userGroupIds:
          type: array
          items:
            type: string
          example:
            - ug_123
        createdAt:
          type: string
          format: date-time
        legacyAt:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          description: >-
            Earliest non-null of this metric's own legacy date and its evaluator
            model's `unselectableAt`, so a model no longer selectable makes
            every metric linked to it report as legacy even though the metric
            row itself is untouched. Present only once that date has passed: a
            scheduled future cutoff reports null, because the metric is still
            active until then. Unlike `disabledAt`, this field never carries a
            future date.
        isActive:
          type: boolean
          readOnly: true
          description: >-
            Whether this is the active revision of its metric: its own legacy
            date is unset, it is not deleted and it is not being optimized.
            Unlike a null `legacyAt`, it ignores the evaluator model, so a
            revision on a model that is no longer selectable is still active.
        disabledAt:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          description: >-
            Earliest non-null of this metric's own disabled date and its
            evaluator model's `disabledAt` — a disabled model makes every metric
            linked to it report as disabled even though the metric row itself is
            untouched.
        unavailableReason:
          type: string
          nullable: true
          readOnly: true
          description: >-
            Why the caller's organization cannot run this metric, or null when
            it can. Set only for an organization whose data region is EU and a
            metric whose judge, or whose decision model for a classifier, has no
            healthy EU deployment: the metric cannot run there until it runs on
            another one. For a metric of your organization, create a revision.
            For a Galtea metric, create a metric of your own. Reported by the
            metric list and read endpoints. An endpoint that returns a metric
            and does not read the organization's data region, such as the
            metrics of a specification, leaves the field out: absent means not
            reported, never that the metric can run.
          example: null
        excludedFromAnalyticsAt:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          description: >-
            When set, results produced by this metric revision do not feed
            analytics.
        excludedByUserId:
          type: string
          nullable: true
          readOnly: true
          description: User who last excluded this metric revision from analytics.
      required:
        - id
        - metricGroupId
        - parentMetricId
        - organizationId
        - userId
        - name
        - evaluationParams
        - source
        - definition
        - judgePrompt
        - tags
        - description
        - documentationUrl
        - evaluatorModelName
        - areEvalParamsTop
        - isBeingOptimized
        - optimizationStatus
        - judgeGenerationSettings
        - passThreshold
        - applicabilityScope
        - applicabilityThreshold
        - classifierQuestion
        - optimizationValidation
        - optimizationRun
        - specificationIds
        - userGroupIds
        - createdAt
        - legacyAt
        - isActive
        - disabledAt
        - excludedFromAnalyticsAt
        - excludedByUserId
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error type
        message:
          type: string
          example: Error message description
    ClassifierQuestion:
      type: object
      properties:
        type:
          type: string
          enum:
            - yes_no
            - scale
        instructions:
          type: string
        goodAnswer:
          type: string
          enum:
            - 'yes'
            - 'no'
        criteria:
          type: object
          nullable: true
          properties:
            'yes':
              type: string
              nullable: true
            'no':
              type: string
              nullable: true
          required:
            - 'yes'
            - 'no'
        levels:
          type: array
          items:
            type: object
            properties:
              description:
                type: string
              score:
                type: number
            required:
              - description
              - score
        doesNotApply:
          type: string
          nullable: true
      required:
        - type
        - instructions
  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.