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

> Get list of evaluations with pagination and filtering. See [Evaluations](https://docs.galtea.ai/concepts/product/version/session/evaluation).

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


## OpenAPI

````yaml /v5.17/openapi.json get /evaluations
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:
  /evaluations:
    get:
      tags:
        - evaluations
      summary: Get evaluations
      description: >-
        Get list of evaluations with pagination and filtering. See
        [Evaluations](https://docs.galtea.ai/concepts/product/version/session/evaluation).
      operationId: getEvaluations
      parameters:
        - schema:
            type: array
            items:
              type: string
            description: Filter by evaluation IDs
          required: false
          description: Filter by evaluation IDs
          style: form
          explode: true
          name: ids
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by product IDs
          required: false
          description: Filter by product IDs
          style: form
          explode: true
          name: productIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by session IDs
          required: false
          description: Filter by session IDs
          style: form
          explode: true
          name: sessionIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by trace IDs (for single-turn evaluations)
          required: false
          description: Filter by trace IDs (for single-turn evaluations)
          style: form
          explode: true
          name: inferenceResultIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by metric IDs
          required: false
          description: Filter by metric IDs
          style: form
          explode: true
          name: metricIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by metric group IDs (matches all revisions of a metric)
          required: false
          description: Filter by metric group IDs (matches all revisions of a metric)
          style: form
          explode: true
          name: metricGroupIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by monitor IDs (returns only evaluations dispatched by the
              given monitors)
          required: false
          description: >-
            Filter by monitor IDs (returns only evaluations dispatched by the
            given monitors)
          style: form
          explode: true
          name: monitorIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by run IDs (returns only evaluations launched by the given
              runs)
          required: false
          description: >-
            Filter by run IDs (returns only evaluations launched by the given
            runs)
          style: form
          explode: true
          name: runIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by monitor alert IDs (returns only the evaluations of the
              sessions the alert linked when it opened (its bad sessions, or its
              sessions with no score), made by the alert's monitor, on the
              alert's metric family, or on the families a Specification alert
              measured when it opened). At most 10 IDs.
            maxItems: 10
          required: false
          description: >-
            Filter by monitor alert IDs (returns only the evaluations of the
            sessions the alert linked when it opened (its bad sessions, or its
            sessions with no score), made by the alert's monitor, on the alert's
            metric family, or on the families a Specification alert measured
            when it opened). At most 10 IDs.
          style: form
          explode: true
          name: monitorAlertIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by test case IDs
          required: false
          description: Filter by test case IDs
          style: form
          explode: true
          name: testCaseIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by test IDs (include only). Use an empty string ("") to
              select evaluations without a test
          required: false
          description: >-
            Filter by test IDs (include only). Use an empty string ("") to
            select evaluations without a test
          style: form
          explode: true
          name: testIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Omit evaluations linked to the specified test IDs. Use an empty
              string ("") to omit evaluations without a test
          required: false
          description: >-
            Omit evaluations linked to the specified test IDs. Use an empty
            string ("") to omit evaluations without a test
          style: form
          explode: true
          name: excludeTestIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by version IDs
          required: false
          description: Filter by version IDs
          style: form
          explode: true
          name: versionIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by specification IDs (returns evaluations whose metric is
              linked to any of the given specifications)
          required: false
          description: >-
            Filter by specification IDs (returns evaluations whose metric is
            linked to any of the given specifications)
          style: form
          explode: true
          name: specificationIds
          in: query
        - schema:
            type: array
            items:
              type: string
              enum:
                - PENDING
                - PENDING_HUMAN
                - SUCCESS
                - FAILED
                - SKIPPED
                - CANCELLED
                - OUTDATED
            description: Filter by evaluation statuses
          required: false
          description: Filter by evaluation statuses
          style: form
          explode: true
          name: statuses
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by evaluation types
          required: false
          description: Filter by evaluation types
          style: form
          explode: true
          name: evaluationTypes
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by metric sources
          required: false
          description: Filter by metric sources
          style: form
          explode: true
          name: metricSources
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Sort instructions (field and direction pairs). Sorting by
              `confidence` puts evaluations with no confidence last in both
              directions. A caller gets 400 for a sort on a field it sees as
              null on any product the list reaches (`evaluation.readInference`).
          required: false
          description: >-
            Sort instructions (field and direction pairs). Sorting by
            `confidence` puts evaluations with no confidence last in both
            directions. A caller gets 400 for a sort on a field it sees as null
            on any product the list reaches (`evaluation.readInference`).
          style: form
          explode: true
          name: sort
          in: query
        - schema:
            type: boolean
            description: Filter evaluations that can be retried
          required: false
          description: Filter evaluations that can be retried
          name: canRetry
          in: query
        - schema:
            type: boolean
            description: Filter evaluations by whether their test case is augmented
          required: false
          description: Filter evaluations by whether their test case is augmented
          name: augmentedTestCase
          in: query
        - schema:
            type: boolean
            description: >-
              Filter by verdict: true returns evaluations whose reported score
              reaches their metric pass threshold, false the ones below it.
              Evaluations with no verdict match neither. Any value other than
              true or false returns 400.
          required: false
          description: >-
            Filter by verdict: true returns evaluations whose reported score
            reaches their metric pass threshold, false the ones below it.
            Evaluations with no verdict match neither. Any value other than true
            or false returns 400.
          name: passed
          in: query
        - schema:
            type: boolean
            description: >-
              Filter evaluations by the joined `Session.isProduction` flag.
              Prefer this over the legacy `testIds`/`excludeTestIds`
              empty-string trick.
          required: false
          description: >-
            Filter evaluations by the joined `Session.isProduction` flag. Prefer
            this over the legacy `testIds`/`excludeTestIds` empty-string trick.
          name: isProduction
          in: query
        - schema:
            type: boolean
            description: >-
              Include evaluations whose metric revision is excluded from
              analytics. Omit or pass false to hide them.
          required: false
          description: >-
            Include evaluations whose metric revision is excluded from
            analytics. Omit or pass false to hide them.
          name: includeExcludedFromAnalytics
          in: query
        - schema:
            type: string
            description: Filter by human evaluator user ID
          required: false
          description: Filter by human evaluator user ID
          name: humanEvaluatorId
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by the launching user's id
          required: false
          description: Filter by the launching user's id
          style: form
          explode: true
          name: userIds
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Filter evaluations created at or after this timestamp (ISO 8601
              format)
          required: false
          description: >-
            Filter evaluations created at or after this timestamp (ISO 8601
            format)
          name: fromCreatedAt
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Filter evaluations created at or before this timestamp (ISO 8601
              format)
          required: false
          description: >-
            Filter evaluations created at or before this timestamp (ISO 8601
            format)
          name: toCreatedAt
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose judge score is greater than this value (0
              to 1). Reads the judge's score, not the human review. An
              evaluation with no judge score never matches. A value outside 0 to
              1 returns 400.
          required: false
          description: >-
            Keep evaluations whose judge score is greater than this value (0 to
            1). Reads the judge's score, not the human review. An evaluation
            with no judge score never matches. A value outside 0 to 1 returns
            400.
          name: scoreGt
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose judge score is greater than or equal to
              this value (0 to 1). Reads the judge's score, not the human
              review. An evaluation with no judge score never matches. A value
              outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose judge score is greater than or equal to this
            value (0 to 1). Reads the judge's score, not the human review. An
            evaluation with no judge score never matches. A value outside 0 to 1
            returns 400.
          name: scoreGte
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose judge score is less than this value (0 to
              1). Reads the judge's score, not the human review. An evaluation
              with no judge score never matches. A value outside 0 to 1 returns
              400.
          required: false
          description: >-
            Keep evaluations whose judge score is less than this value (0 to 1).
            Reads the judge's score, not the human review. An evaluation with no
            judge score never matches. A value outside 0 to 1 returns 400.
          name: scoreLt
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose judge score is less than or equal to this
              value (0 to 1). Reads the judge's score, not the human review. An
              evaluation with no judge score never matches. A value outside 0 to
              1 returns 400.
          required: false
          description: >-
            Keep evaluations whose judge score is less than or equal to this
            value (0 to 1). Reads the judge's score, not the human review. An
            evaluation with no judge score never matches. A value outside 0 to 1
            returns 400.
          name: scoreLte
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose human review score is greater than this
              value (0 to 1). An evaluation with no human score never matches. A
              value outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose human review score is greater than this value
            (0 to 1). An evaluation with no human score never matches. A value
            outside 0 to 1 returns 400.
          name: humanScoreGt
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose human review score is greater than or equal
              to this value (0 to 1). An evaluation with no human score never
              matches. A value outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose human review score is greater than or equal
            to this value (0 to 1). An evaluation with no human score never
            matches. A value outside 0 to 1 returns 400.
          name: humanScoreGte
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose human review score is less than this value
              (0 to 1). An evaluation with no human score never matches. A value
              outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose human review score is less than this value (0
            to 1). An evaluation with no human score never matches. A value
            outside 0 to 1 returns 400.
          name: humanScoreLt
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose human review score is less than or equal to
              this value (0 to 1). An evaluation with no human score never
              matches. A value outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose human review score is less than or equal to
            this value (0 to 1). An evaluation with no human score never
            matches. A value outside 0 to 1 returns 400.
          name: humanScoreLte
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose classifier confidence is greater than this
              value (0 to 1). An evaluation with no confidence never matches. A
              value outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose classifier confidence is greater than this
            value (0 to 1). An evaluation with no confidence never matches. A
            value outside 0 to 1 returns 400.
          name: confidenceGt
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose classifier confidence is greater than or
              equal to this value (0 to 1). An evaluation with no confidence
              never matches. A value outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose classifier confidence is greater than or
            equal to this value (0 to 1). An evaluation with no confidence never
            matches. A value outside 0 to 1 returns 400.
          name: confidenceGte
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose classifier confidence is less than this
              value (0 to 1). An evaluation with no confidence never matches. A
              value outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose classifier confidence is less than this value
            (0 to 1). An evaluation with no confidence never matches. A value
            outside 0 to 1 returns 400.
          name: confidenceLt
          in: query
        - schema:
            type: number
            description: >-
              Keep evaluations whose classifier confidence is less than or equal
              to this value (0 to 1). An evaluation with no confidence never
              matches. A value outside 0 to 1 returns 400.
          required: false
          description: >-
            Keep evaluations whose classifier confidence is less than or equal
            to this value (0 to 1). An evaluation with no confidence never
            matches. A value outside 0 to 1 returns 400.
          name: confidenceLte
          in: query
        - schema:
            type: integer
            minimum: 0
            maximum: 9007199254740991
            default: 10000
            description: Maximum number of results
          required: false
          description: Maximum number of results
          name: limit
          in: query
        - schema:
            type: integer
            minimum: 0
            default: 0
            description: Number of results to skip
          required: false
          description: Number of results to skip
          name: offset
          in: query
      responses:
        '200':
          description: Evaluations retrieved successfully
          headers:
            Content-Range:
              schema:
                type: string
                description: >-
                  Pagination range as `evaluations
                  <offset>-<upperBound>/<total>`.
              required: true
              description: Pagination range as `evaluations <offset>-<upperBound>/<total>`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Evaluation'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Evaluation:
      type: object
      properties:
        id:
          type: string
          example: eval_123
        metricId:
          type: string
          example: metric_123
        sessionId:
          type: string
          example: session_123
        productId:
          type: string
          nullable: true
          example: product_123
          description: Product the evaluated session belongs to
        userId:
          type: string
          nullable: true
          example: user_123
        status:
          type: string
          enum:
            - PENDING
            - PENDING_HUMAN
            - SUCCESS
            - FAILED
            - SKIPPED
            - CANCELLED
            - OUTDATED
          example: SUCCESS
        inferenceResultId:
          type: string
          nullable: true
          example: ir_123
        score:
          type: number
          nullable: true
          example: 0.95
        reason:
          type: string
          nullable: true
          example: High quality response
        error:
          type: string
          nullable: true
        canRetry:
          type: boolean
          example: false
        creditsUsed:
          type: integer
          nullable: true
          example: 1
        judgeInputTokens:
          type: integer
          nullable: true
          example: 4100
          description: Tokens the judge received, prompt plus session content
        judgeOutputTokens:
          type: integer
          nullable: true
          example: 16800
          description: Tokens the judge produced, reasoning included
        judgeReasoningTokens:
          type: integer
          nullable: true
          example: 12400
          description: Reasoning tokens, a subset of judgeOutputTokens
        conversationSimulatorVersion:
          type: string
          nullable: true
          example: 1.0.0
        humanEvaluatorId:
          type: string
          nullable: true
          description: User ID of the human evaluator
        humanEvaluatorStartedAt:
          type: string
          format: date-time
          nullable: true
        humanScore:
          type: number
          nullable: true
          description: Human-provided annotation score
        humanReason:
          type: string
          nullable: true
          description: Human-provided annotation reason
        humanEvaluatorFinishedAt:
          type: string
          nullable: true
          format: date-time
          description: Timestamp when human evaluation was submitted
        failedTurns:
          type: array
          items:
            type: string
          description: Conversation turns that failed
        monitorId:
          type: string
          nullable: true
          description: ID of the monitor that dispatched this evaluation
        monitorSettledAtTurn:
          type: integer
          nullable: true
          description: Session turn count when the monitor scored it
        monitorSamplingPercentage:
          type: number
          nullable: true
          description: Sampling percentage in effect when the monitor scored this session
        runId:
          type: string
          nullable: true
          description: ID of the run that launched this evaluation
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
        evaluatedAt:
          type: string
          format: date-time
          nullable: true
        metricLegacyAt:
          type: string
          format: date-time
          nullable: true
        passed:
          type: boolean
          nullable: true
          description: >-
            Whether the reported score (the reviewer's when set, else the
            judge's) reaches the metric's pass threshold. Null when the
            evaluation has no reported score, is outdated or deleted, is a long
            classifier input, or its metric is not loaded.
        metricPassThreshold:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            The pass threshold that decides `passed`: the metric's, copied onto
            the evaluation when it was created.
        metricDisabledAt:
          type: string
          format: date-time
          nullable: true
        metricExcludedFromAnalyticsAt:
          type: string
          format: date-time
          nullable: true
        metricExcludedByUserId:
          type: string
          nullable: true
        testCaseLegacyAt:
          type: string
          format: date-time
          nullable: true
        scoreBreakdown:
          type: object
          nullable: true
          properties:
            version:
              type: integer
            model:
              type: string
            type:
              type: string
              enum:
                - yes_no
                - scale
            value:
              type: number
            confidence:
              type: number
              nullable: true
            pYes:
              type: number
              minimum: 0
              maximum: 1
            goodAnswer:
              type: string
              enum:
                - 'yes'
                - 'no'
            probabilities:
              type: object
              additionalProperties:
                type: number
              description: Per level index, the "does not apply" index included.
            levelScores:
              type: array
              items:
                type: number
            doesNotApply:
              type: boolean
              description: Whether the question had a "does not apply" level.
          required:
            - version
            - model
            - type
            - value
            - confidence
          description: >-
            CLASSIFIER only: what the classifier answered; null for every other
            source.
        confidence:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          example: 0.9
          description: >-
            CLASSIFIER only: how sure the classifier was, from 0 to 1; null for
            every other source. Values do not compare across question types.
        longInput:
          type: boolean
          description: >-
            True for a CLASSIFIER evaluation whose input ran past what the
            classifier scores reliably (CLASSIFIER_RELIABLE_INPUT_TOKENS judge
            input tokens) and that no reviewer has scored; false for every other
            evaluation.
      required:
        - id
        - metricId
        - sessionId
        - productId
        - userId
        - status
        - inferenceResultId
        - score
        - reason
        - error
        - canRetry
        - creditsUsed
        - judgeInputTokens
        - judgeOutputTokens
        - judgeReasoningTokens
        - conversationSimulatorVersion
        - humanEvaluatorId
        - humanEvaluatorStartedAt
        - humanScore
        - humanReason
        - humanEvaluatorFinishedAt
        - failedTurns
        - monitorId
        - monitorSettledAtTurn
        - monitorSamplingPercentage
        - runId
        - deletedAt
        - evaluatedAt
        - metricLegacyAt
        - passed
        - metricPassThreshold
        - metricDisabledAt
        - metricExcludedFromAnalyticsAt
        - metricExcludedByUserId
        - testCaseLegacyAt
        - scoreBreakdown
        - confidence
        - longInput
    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.