---
title: "Get Lipsync Batch"
method: GET
path: "/v3/lipsyncs/batches/{batch_id}"
tags: ["Lipsync Batches"]
---

# Get Lipsync Batch

`GET /v3/lipsyncs/batches/{batch_id}`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/lipsyncs/batches/{batch_id}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API).

## Path parameters

- `batch_id` string, required

## Query parameters

- `limit` integer
- `token` string

## Response `200`

Successful response

- object
  - `data` VideoBatchDetail
    - `batch_id` string, required: Batch identifier.
    - `title` string, nullable: Batch display name.
    - `status` 'processing' | 'completed' | 'failed', required
    - `total_items` integer, required: Number of items submitted in this batch.
    - `counts_by_status` object, required: Item counts keyed by item status.
    - `created_at` integer, required: Batch creation time as a unix timestamp.
    - `items` VideoBatchItem[], required: One page of batch items ordered by item_index.
      - `item_index` integer, required: Zero-based position of this item in the submitted videos array.
      - `status` 'queued' | 'processing' | 'completed' | 'failed', required
      - `video_id` string, nullable: Video id, present once the underlying video has been created.
      - `error` object, nullable: Failure details when status is failed.
    - `has_more` boolean, required: Whether more items exist beyond this page.
    - `next_token` string, nullable: Opaque cursor for the next page of items.

## 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/lipsyncs/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)