---
title: "Get Video Quality Comparison Batch"
method: GET
path: "/v3/video-quality/comparisons/batches/{batch_id}"
tags: ["Video Quality"]
---

# Get Video Quality Comparison Batch

`GET /v3/video-quality/comparisons/batches/{batch_id}`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/video-quality/comparisons/batches/{batch_id}`
- Auth: API key in header `x-api-key`

Return aggregate batch status and one cursor-paginated page of comparison items.

## Path parameters

- `batch_id` string, required

## Query parameters

- `limit` integer
- `token` string

## Response `200`

Successful response

- object
  - `data` VideoQualityComparisonBatchResponse: Current state and one page of results for an asynchronous batch.
    - `batch_id` string, required: Unique batch identifier.
    - `status` 'processing' | 'completed' | 'failed', required: Lifecycle shared by single comparisons and batches.
    - `total_items` integer, required: Total comparisons in this batch.
    - `counts` VideoQualityComparisonBatchCounts, required: Aggregate batch item counts.
      - `processing` integer, required: Number of comparisons still processing.
      - `completed` integer, required: Number of successfully completed comparisons.
      - `failed` integer, required: Number of terminally failed comparisons.
    - `items` VideoQualityComparisonBatchItem[], required: Stable, ordered page of comparison results.
      - `item_index` integer, required: Zero-based position of this comparison in the submitted batch.
      - `comparison` VideoQualityComparisonResponse, required: A comparison resource returned by synchronous submission or polling.
        - `comparison_id` string, required: Unique comparison identifier used for polling.
        - `status` 'processing' | 'completed' | 'failed', required: Lifecycle shared by single comparisons and batches.
        - `result` VideoQualityComparisonResult: Completed pairwise judge result.
          - `model_a` string, required: Caller-supplied identifier for video A's model.
          - `model_b` string, required: Caller-supplied identifier for video B's model.
          - `winner` string, required: Winning caller-supplied model identifier.
          - `winner_side` 'a' | 'b', required: Winning candidate side: 'a' or 'b'.
          - `confidence` number, required: Winning-side probability derived from the pairwise judge.
          - `question_id` 'engagement' | 'prompt_intent' | 'composition' | 'temporal_consistency' | 'craft' | 'q1', required: Supported C2V judge questions.
          - `judge_model_version` string, required: Exact judge model version used for this comparison.
        - `error` VideoQualityComparisonError: Terminal per-comparison error returned by polling endpoints.
          - `code` string, required: Stable machine-readable failure code.
          - `message` string, required: Human-readable explanation of the comparison failure.
        - `resolved_assets` VideoQualityResolvedAssets
          - `video_a_asset_id` string, required: Owned video A asset ID, reusable as an asset_id input in later comparisons or batches.
          - `video_b_asset_id` string, required: Owned video B asset ID, reusable as an asset_id input in later comparisons or batches.
    - `has_more` boolean, required: Whether another page of batch items is available.
    - `next_token` string, nullable: Opaque cursor for the next page when has_more is true.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `404`: Resource not found
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/video-quality/comparisons/batches/:batch_id/get.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)