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

# 유닛 테스트 실행 조회

> 실행한 대화와 항목별 채점을 돌려줍니다. `checks[].transcript_index`는 채점한 `transcript` 항목의 위치입니다. `status`는 진행 상태, `result`는 채점 결과입니다.



## OpenAPI

````yaml /api-reference/v3/openapi.json get /evals/unit/runs/{run_id}
openapi: 3.1.0
info:
  title: vox.ai API
  description: >
    vox.ai API v3


    ### v3 공개 계약 규칙


    - 인증은 `Authorization: Bearer <token>` 헤더를 사용합니다. 워크스페이스 API 키를 Bearer 토큰으로
    전달합니다.

    - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다.

    - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`,
    `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다.

    - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix
    seconds도 허용하고 milliseconds로 정규화합니다.

    - 대량 발신 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM`
    문자열(`start_time` / `end_time`)을 사용합니다.

    - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`,
    `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다.

    - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우
    `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다.
  version: 3.0.0
servers:
  - url: https://client-api.tryvox.co/v3
    description: 운영
security: []
paths:
  /evals/unit/runs/{run_id}:
    get:
      tags:
        - Evals
      summary: 유닛 테스트 실행 조회
      description: >-
        실행한 대화와 항목별 채점을 돌려줍니다. `checks[].transcript_index`는 채점한 `transcript` 항목의
        위치입니다. `status`는 진행 상태, `result`는 채점 결과입니다.
      operationId: getUnitTestRun
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: 실행 id입니다. GET /v3/evals/unit/runs 응답의 id를 사용합니다.
            title: Run Id
          description: 실행 id입니다. GET /v3/evals/unit/runs 응답의 id를 사용합니다.
      responses:
        '200':
          description: 성공 응답
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnitTestRunResponse'
              example:
                id: 6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d
                test_id: 0f9c2b1e-3d4a-4b5c-8d6e-7f8091a2b3c4
                batch_id: 3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f
                status: completed
                result: passed
                agent:
                  agent_id: 8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d
                  agent_version: v3
                created_at: 1761960000000
                started_at: 1761960002000
                finished_at: 1761960015000
                error_message: null
                checks:
                  - result: passed
                    reason: 확인한 예약 날짜를 말하고 바꿀 날짜를 물었습니다.
                    transcript_index: 3
                transcript:
                  - role: user
                    content: 예약 바꾸려고요
                  - role: tool_call_invocation
                    tool_call_id: c1
                    name: lookup_booking
                    arguments:
                      phone: '01012345678'
                  - role: tool_call_result
                    tool_call_id: c1
                    content: '{"date": "11-03"}'
                  - role: agent
                    content: 11월 3일 예약 확인했어요. 언제로 바꿔 드릴까요?
                run_cost:
                  status: confirmed
                  total_cost: '12.50'
                flow_start_node_id: null
                metadata:
                  team: cs
        '400':
          description: 요청 검증 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validationError:
                  summary: 요청 검증 오류
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Request validation failed.
                      details:
                        field: name
                        reason: must not be blank
        '401':
          description: 인증이 필요합니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Bearer 토큰 누락 또는 오류
                  value:
                    error:
                      code: UNAUTHORIZED
                      message: Authentication is required.
                      details: {}
        '403':
          description: 권한이 없습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: 권한이 없습니다.
                  value:
                    error:
                      code: FORBIDDEN
                      message: Permission denied.
                      details: {}
        '404':
          description: 리소스를 찾을 수 없습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  summary: 리소스를 찾을 수 없습니다.
                  value:
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: Resource not found.
                      details:
                        resource: agent
        '409':
          description: 충돌이 발생했습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                conflict:
                  summary: 상태 충돌이 발생했습니다.
                  value:
                    error:
                      code: CONFLICT
                      message: The requested operation conflicts with current state.
                      details:
                        current_status: draft
        '429':
          description: >-
            요청 한도를 초과했습니다. API 키 트래픽은 기본값으로 워크스페이스당 초당 5회·분당 120회, Supabase JWT
            트래픽은 기본값으로 사용자당 초당 10회·분당 240회로 제한되며, 워크스페이스 대시보드에는 기본 분당 2,400회의
            백스톱 한도가 적용됩니다. 한도는 운영자가 조정할 수 있고, 초과한 버킷의 실제 한도와 윈도우는 429 응답의
            X-RateLimit-Limit·X-RateLimit-Window 헤더로 알려 줍니다. 개별 경로 자체 리미터가 만든
            429 응답에는 이 헤더가 없을 수 있습니다.
          headers:
            Retry-After:
              description: >-
                초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우가 초기화될 때까지 남은 시간입니다. 단위는
                초입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Limit:
              description: >-
                초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 최대 요청 수입니다. 개별 경로 자체
                리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Window:
              description: >-
                초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 길이입니다. 단위는 초입니다. 개별 경로
                자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rateLimited:
                  summary: 요청 한도를 초과했습니다.
                  value:
                    error:
                      code: RATE_LIMIT_EXCEEDED
                      message: Too many requests.
                      details:
                        limit: 10
                        window_seconds: 1
                        scope: user
        '500':
          description: 서버 내부 오류가 발생했습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internalError:
                  summary: 서버 내부 오류가 발생했습니다.
                  value:
                    error:
                      code: INTERNAL_ERROR
                      message: Internal server error.
                      details: {}
        '503':
          description: 서비스를 일시적으로 사용할 수 없습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                serviceUnavailable:
                  summary: 서비스를 일시적으로 사용할 수 없습니다.
                  value:
                    error:
                      code: SERVICE_UNAVAILABLE
                      message: Service temporarily unavailable.
                      details: {}
      security:
        - BearerAuth: []
components:
  schemas:
    UnitTestRunResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: 실행 id입니다.
        test_id:
          type: string
          format: uuid
          title: Test Id
          description: 실행한 테스트 id입니다.
        batch_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Batch Id
          description: 이 실행이 속한 배치 id입니다.
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - error
          title: Status
          description: 실행 진행 상태입니다. completed는 실행이 끝났다는 뜻이며 통과 여부는 `result`로 봅니다.
        result:
          anyOf:
            - type: string
              enum:
                - passed
                - failed
                - error
            - type: 'null'
          title: Result
          description: 판정 결과입니다. 실행이 끝나기 전에는 null입니다.
        agent:
          anyOf:
            - $ref: '#/components/schemas/AgentMapping'
            - type: 'null'
          description: 실행한 에이전트와 버전입니다. 버전을 고르지 않고 실행했으면 `agent_version`은 `current`입니다.
        created_at:
          type: integer
          title: Created At
          description: 리소스 생성 시각입니다. unix milliseconds 형식입니다.
        started_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Started At
          description: 실행을 시작한 시각입니다(unix ms). 시작 전이면 null입니다.
        finished_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Finished At
          description: 실행이 끝난 시각입니다(unix ms). 끝나기 전이면 null입니다.
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
          description: 실행이 오류로 끝났을 때의 안내 문장입니다. 그 밖에는 null입니다.
        checks:
          items:
            $ref: '#/components/schemas/UnitTestCheck'
          type: array
          title: Checks
          description: 검사별 판정 결과입니다.
        transcript:
          items:
            oneOf:
              - $ref: '#/components/schemas/EvalTranscriptUserMessage'
              - $ref: '#/components/schemas/EvalTranscriptAgentMessage'
              - $ref: '#/components/schemas/EvalTranscriptToolCallInvocation'
              - $ref: '#/components/schemas/EvalTranscriptToolCallResult'
            discriminator:
              propertyName: role
              mapping:
                agent: '#/components/schemas/EvalTranscriptAgentMessage'
                tool_call_invocation: '#/components/schemas/EvalTranscriptToolCallInvocation'
                tool_call_result: '#/components/schemas/EvalTranscriptToolCallResult'
                user: '#/components/schemas/EvalTranscriptUserMessage'
          type: array
          title: Transcript
          description: 실행한 대화입니다. 통화 transcript와 같은 항목을 순서대로 담습니다.
        run_cost:
          $ref: '#/components/schemas/EvalRunCost'
          description: 이 실행의 사용료입니다.
        flow_start_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Flow Start Node Id
          description: Flow 유닛 테스트를 시작한 노드 id입니다. 일반 에이전트 실행은 null입니다.
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: 실행 계획에 붙인 사용자 정의 정보입니다.
      type: object
      required:
        - id
        - test_id
        - batch_id
        - status
        - result
        - agent
        - created_at
        - started_at
        - finished_at
        - error_message
        - checks
        - transcript
        - run_cost
        - flow_start_node_id
        - metadata
      title: UnitTestRunResponse
      examples:
        - agent:
            agent_id: 8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d
            agent_version: v3
          batch_id: 3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f
          checks:
            - reason: 확인한 예약 날짜를 말하고 바꿀 날짜를 물었습니다.
              result: passed
              transcript_index: 3
          created_at: 1761960000000
          finished_at: 1761960015000
          id: 6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d
          metadata:
            team: cs
          result: passed
          run_cost:
            status: confirmed
            total_cost: '12.50'
          started_at: 1761960002000
          status: completed
          test_id: 0f9c2b1e-3d4a-4b5c-8d6e-7f8091a2b3c4
          transcript:
            - content: 예약 바꾸려고요
              role: user
            - arguments:
                phone: '01012345678'
              name: lookup_booking
              role: tool_call_invocation
              tool_call_id: c1
            - content: '{"date": "11-03"}'
              role: tool_call_result
              tool_call_id: c1
            - content: 11월 3일 예약 확인했어요. 언제로 바꿔 드릴까요?
              role: agent
    ErrorResponse:
      type: object
      required:
        - error
      title: ErrorResponse
      description: 모든 실패 응답에서 사용하는 v3 error envelope입니다.
      examples:
        - error:
            code: VALIDATION_ERROR
            message: Request validation failed.
            details:
              field: name
              reason: must not be blank
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: 오류 payload입니다.
    AgentMapping:
      additionalProperties: false
      description: >-
        `agent_id`와 `agent_version` 매핑입니다.


        요청·응답 모두에서 에이전트 매핑이 필요한 경우 이 타입을 사용합니다. version 지정이 필요 없는 엔드포인트는 flat
        `agent_id: UUID`를 직접 받고 `AgentMapping`을 사용하지 않습니다.
      properties:
        agent_id:
          description: 에이전트 UUID입니다.
          format: uuid
          title: Agent Id
          type: string
          x-vox-effect: wiring
        agent_version:
          default: current
          description: >-
            에이전트 버전입니다. 허용값은 "current", "production", "v{n}"(n≥1)입니다. 보내지 않으면
            "current"로 처리합니다. null 전송은 거부합니다.
          title: Agent Version
          type: string
          x-vox-effect: wiring
          pattern: ^(current|production|v[1-9][0-9]*)$
          examples:
            - current
            - production
            - v1
      required:
        - agent_id
      title: AgentMapping
      type: object
    UnitTestCheck:
      properties:
        result:
          type: string
          enum:
            - passed
            - failed
            - error
          title: Result
          description: 이 검사의 판정 결과입니다.
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          description: 판정 이유입니다.
        transcript_index:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Transcript Index
          description: 판정한 항목의 `transcript` 위치(0부터)입니다. 판정할 항목이 없었으면 null입니다.
      type: object
      required:
        - result
        - reason
        - transcript_index
      title: UnitTestCheck
    EvalTranscriptUserMessage:
      properties:
        role:
          type: string
          const: user
          title: Role
          description: 고객 발화 항목입니다.
        content:
          type: string
          title: Content
          description: 고객 발화 내용입니다.
      type: object
      required:
        - role
        - content
      title: EvalTranscriptUserMessage
    EvalTranscriptAgentMessage:
      properties:
        role:
          type: string
          const: agent
          title: Role
          description: 에이전트 응답 항목입니다.
        content:
          type: string
          title: Content
          description: 에이전트 응답 내용입니다.
      type: object
      required:
        - role
        - content
      title: EvalTranscriptAgentMessage
    EvalTranscriptToolCallInvocation:
      properties:
        role:
          type: string
          const: tool_call_invocation
          title: Role
          description: 에이전트의 도구 호출 항목입니다.
        tool_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Id
          description: 도구 호출 id입니다. 저장된 id가 없으면 null입니다.
        name:
          type: string
          title: Name
          description: 호출한 도구 이름입니다.
        arguments:
          anyOf:
            - additionalProperties: true
              type: object
            - type: string
          title: Arguments
          description: 도구 호출에 보낸 값입니다. JSON 객체로 읽을 수 없으면 원래 문자열을 그대로 돌려줍니다.
      type: object
      required:
        - role
        - tool_call_id
        - name
        - arguments
      title: EvalTranscriptToolCallInvocation
    EvalTranscriptToolCallResult:
      properties:
        role:
          type: string
          const: tool_call_result
          title: Role
          description: 도구 호출 결과 항목입니다.
        tool_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Id
          description: 대응하는 도구 호출 id입니다. 저장된 id가 없으면 null입니다.
        content:
          type: string
          title: Content
          description: 도구 결과 문자열입니다.
      type: object
      required:
        - role
        - tool_call_id
        - content
      title: EvalTranscriptToolCallResult
    EvalRunCost:
      properties:
        status:
          type: string
          enum:
            - pending
            - confirmed
          title: Status
          description: 사용료 확정 상태입니다.
        total_cost:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Cost
          description: 확정된 사용료(KRW) 문자열입니다. 확정 전이면 null이고, 오류로 끝나 과금하지 않은 실행은 `0.00`입니다.
      type: object
      required:
        - status
        - total_cost
      title: EvalRunCost
    ErrorDetail:
      type: object
      required:
        - code
        - message
        - details
      title: ErrorDetail
      description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다.
      examples:
        - code: VALIDATION_ERROR
          message: Request validation failed.
          details:
            field: name
            reason: must not be blank
      properties:
        code:
          type: string
          title: Code
          description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다.
          examples:
            - VALIDATION_ERROR
        message:
          type: string
          title: Message
          description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다.
          examples:
            - Request validation failed.
        details:
          type: object
          title: Details
          additionalProperties: true
          description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Organization API key
      description: '워크스페이스 API 키를 `Authorization: Bearer <token>` 형식으로 보냅니다.'

````

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