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

# Claim an evaluation for human review or annotation

> Claim an evaluation to prevent concurrent editing. For HUMAN_EVALUATION metrics, enforces user group permissions (admins skip). For other metrics, works as an annotation claim open to all org members. Works on any evaluation status. Sets humanEvaluatorStartedAt timestamp. See [Evaluations](https://docs.galtea.ai/concepts/product/version/session/evaluation).

> [!WARNING]
>
> You are reading the docs of Galtea 5.10. [Read this page in the latest version](https://docs.galtea.ai/api-reference/evaluations/claim-an-evaluation-for-human-review-or-annotation.md).


## OpenAPI

````yaml /v5.10/openapi.json post /evaluations/{id}/claim
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/{id}/claim:
    post:
      tags:
        - evaluations
      summary: Claim an evaluation for human review or annotation
      description: >-
        Claim an evaluation to prevent concurrent editing. For HUMAN_EVALUATION
        metrics, enforces user group permissions (admins skip). For other
        metrics, works as an annotation claim open to all org members. Works on
        any evaluation status. Sets humanEvaluatorStartedAt timestamp. See
        [Evaluations](https://docs.galtea.ai/concepts/product/version/session/evaluation).
      operationId: claimHumanEvaluation
      parameters:
        - schema:
            type: string
            description: Evaluation ID
            example: eval_123
          required: true
          description: Evaluation ID
          name: id
          in: path
      responses:
        '200':
          description: Evaluation claimed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluation'
        '400':
          description: Evaluation is already being evaluated or not in PENDING_HUMAN status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: User not authorized to evaluate this metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Evaluation not found
          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
          nullable: true
          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
          nullable: true
          format: date-time
        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
          nullable: true
          format: date-time
        evaluatedAt:
          type: string
          nullable: true
          format: date-time
        metricLegacyAt:
          type: string
          nullable: true
          format: date-time
        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
          nullable: true
          format: date-time
        metricExcludedFromAnalyticsAt:
          type: string
          nullable: true
          format: date-time
        metricExcludedByUserId:
          type: string
          nullable: true
        testCaseLegacyAt:
          type: string
          nullable: true
          format: date-time
        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.