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

# Complete/finalize an evaluation run

> Complete/fail a run, reporting final completeness counts.

<Note>The TraceRoot SDKs call this endpoint for you; call it directly only where no SDK fits. It accepts a project API key only.</Note>


## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/public/evaluation-runs/{run_id}/complete
openapi: 3.1.0
info:
  title: TraceRoot Public API
  version: 0.1.0
servers:
  - description: TraceRoot Cloud
    url: https://app.traceroot.ai
  - description: Self-hosted
    url: '{baseUrl}'
    variables:
      baseUrl:
        default: http://localhost:8000
        description: Your TraceRoot backend URL
security: []
paths:
  /api/v1/public/evaluation-runs/{run_id}/complete:
    post:
      tags:
        - Offline Eval
      summary: Complete/finalize an evaluation run
      description: Complete/fail a run, reporting final completeness counts.
      operationId: complete_run
      parameters:
        - in: path
          name: run_id
          required: true
          schema:
            title: Run Id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteRunRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompleteRunResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication failed
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request body too large
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication service unavailable
      security:
        - BearerAuth: []
components:
  schemas:
    CompleteRunRequest:
      description: Complete/fail a run, reporting final completeness counts.
      properties:
        case_count:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
          title: Case Count
        scored_count:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
          title: Scored Count
        scorer_error_count:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
          title: Scorer Error Count
        scorers:
          anyOf:
            - items:
                $ref: '#/components/schemas/ScorerRef'
              maxItems: 200
              type: array
            - type: 'null'
          title: Scorers
        status:
          enum:
            - running
            - completed
            - completed_with_errors
            - failed
            - incomplete
            - cancelled
          title: Status
          type: string
        task_error_count:
          anyOf:
            - maximum: 9007199254740991
              minimum: 0
              type: integer
            - type: 'null'
          title: Task Error Count
      required:
        - status
      title: CompleteRunRequest
      type: object
    CompleteRunResponse:
      properties:
        evaluation_run_id:
          title: Evaluation Run Id
          type: string
        status:
          enum:
            - running
            - completed
            - completed_with_errors
            - failed
            - incomplete
            - cancelled
          title: Status
          type: string
      required:
        - evaluation_run_id
        - status
      title: CompleteRunResponse
      type: object
    ErrorResponse:
      description: >-
        The canonical public error envelope (matches the gateway's normalized
        shape).
      properties:
        detail:
          title: Detail
          type: string
      required:
        - detail
      title: ErrorResponse
      type: object
    ScorerRef:
      description: >-
        A scorer's descriptor. ``key`` is the stable SEMANTIC comparison
        identity

        (it defaults to ``name`` when omitted — see below);
        ``name``/``version``/

        ``language``/``source`` are provenance, NOT identity. The richer
        metadata is

        optional and back-compatible (an old SDK sending only ``{name,
        version}`` stays

        valid — its ``key`` falls back to ``name``). Mirrors the non-strict

        ``ScorerRefSchema``, so unknown keys are ignored rather than rejected.


        The DEFINITION fields (``scorer_type``, prompt/source, config) let the
        read-only

        Scorer detail render an LLM judge's model + messages or a code scorer's
        snippet.


        ``scorer_type`` / ``output_type`` / ``language`` are display-only, so an

        unrecognised value from a newer SDK degrades to ``None`` rather than
        failing

        run registration (which would lose the run's every result and score) —

        matching ``.catch(null)`` on the Zod side. The vocabularies that drive

        persistence and aggregation still reject.
      properties:
        description:
          anyOf:
            - maxLength: 2000
              type: string
            - type: 'null'
          title: Description
        direction:
          anyOf:
            - enum:
                - higher_is_better
                - lower_is_better
                - none
              type: string
            - type: 'null'
          title: Direction
        emitted_metrics:
          anyOf:
            - items:
                $ref: '#/components/schemas/EmittedMetric'
              maxItems: 20
              type: array
            - type: 'null'
          title: Emitted Metrics
        key:
          anyOf:
            - maxLength: 200
              minLength: 1
              type: string
            - type: 'null'
          title: Key
        language:
          anyOf:
            - enum:
                - python
                - typescript
              type: string
            - type: 'null'
          title: Language
        messages:
          anyOf:
            - items:
                $ref: '#/components/schemas/ScorerMessage'
              maxItems: 50
              type: array
            - type: 'null'
          title: Messages
        metadata:
          anyOf:
            - {}
            - type: 'null'
          title: Metadata
        model:
          anyOf:
            - maxLength: 200
              type: string
            - type: 'null'
          title: Model
        name:
          maxLength: 200
          minLength: 1
          title: Name
          type: string
        output_type:
          anyOf:
            - enum:
                - score
                - classification
              type: string
            - type: 'null'
          title: Output Type
        required_inputs:
          anyOf:
            - items:
                maxLength: 100
                minLength: 1
                type: string
              maxItems: 20
              type: array
            - type: 'null'
          title: Required Inputs
        scorer_type:
          anyOf:
            - enum:
                - llm_judge
                - code
              type: string
            - type: 'null'
          title: Scorer Type
        source:
          anyOf:
            - maxLength: 50000
              type: string
            - type: 'null'
          title: Source
        threshold:
          anyOf:
            - type: number
            - type: 'null'
          title: Threshold
        value_type:
          anyOf:
            - enum:
                - numeric
                - boolean
                - categorical
              type: string
            - type: 'null'
          title: Value Type
        version:
          maxLength: 50
          minLength: 1
          title: Version
          type: string
      required:
        - name
        - version
      title: ScorerRef
      type: object
    EmittedMetric:
      description: >-
        One metric a scorer DEFINITION emits, with its own comparison policy.
        The metric

        ``name`` is the EMITTED-METRIC identity (what a Score row reports as
        ``scorer_name``),

        distinct from the scorer DEFINITION name. Mirrors
        ``EmittedMetricSchema``.
      properties:
        direction:
          anyOf:
            - enum:
                - higher_is_better
                - lower_is_better
                - none
              type: string
            - type: 'null'
          title: Direction
        name:
          maxLength: 200
          minLength: 1
          title: Name
          type: string
        threshold:
          anyOf:
            - type: number
            - type: 'null'
          title: Threshold
        value_type:
          anyOf:
            - enum:
                - numeric
                - boolean
                - categorical
              type: string
            - type: 'null'
          title: Value Type
      required:
        - name
      title: EmittedMetric
      type: object
    ScorerMessage:
      description: One prompt message of an LLM-judge scorer's definition.
      properties:
        content:
          maxLength: 20000
          title: Content
          type: string
        role:
          maxLength: 50
          minLength: 1
          title: Role
          type: string
      required:
        - role
        - content
      title: ScorerMessage
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http

````

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