---
title: "Find Caption Matches"
method: POST
path: "/caption_matches"
tags: ["Captions"]
---

# Find Caption Matches

`POST /caption_matches`

## Request

- Base URL: `https://api.wistia.com/modern`
- URL: `https://api.wistia.com/modern/caption_matches`
- Auth: HTTP bearer

Finds exact text in caption tracks without modifying them. Matching uses the
same normalization, composite-media boundaries, and time coordinates as the
targeted caption edit endpoint. Fuzzy alternatives are returned separately
as suggestions and are never reported as exact matches. A resolved match
means the wording was located; a later write can still fail authorization,
version, or edit-boundary checks.

When more than 10 exact matches exist, use the one-based `occurrence`
parameter to retrieve a specific later match.

Authentication and request validation failures apply to the whole request.
Missing, inaccessible, or otherwise unreadable media are reported as
per-media statuses without exposing whether an inaccessible ID exists.

## Requires api token with one of the following permissions
```
Read all folder and media data
```

Tokens with the "Act with a team member's permissions" permission
(`all:delegate_to_contact_permissions` scope) can also be used.

## Headers

- `X-Wistia-API-Version` string, required

## Request body

- object
  - `media_ids` string[], required: Explicit hashed IDs of the media whose captions should be searched.
  - `target_text` string, required: Exact caption wording to locate.
  - `language_code` string: Exact IETF language tag. Omit when each media has only one caption track.
  - `occurrence` integer: One-based exact occurrence to return, including occurrences after the first 10.
  - `start_ms` integer: Optional start of a time range used to disambiguate the match.
  - `end_ms` integer: Optional end of a time range used to disambiguate the match.

## Response `200`

Every requested media ID was processed; inspect each result's status.

- object
  - `requested_count` integer, required
  - `succeeded_count` integer, required: Number of media whose transcript search was processed successfully, whether or not an exact match was found.
  - `failed_count` integer, required: Number of media that returned a non-ok per-media status.
  - `complete` boolean, required: True when every requested media ID was processed, including per-media negative results.
  - `results` object[], required
    - `media_hashed_id` string, required
    - `status` 'ok' | 'media_not_found' | 'invalid_media' | 'no_tracks' | 'language_required' | 'track_not_found' | 'no_active_payload' | 'response_too_large', required
    - `tracks` object[]
      - `id` string, required
      - `language` string, required
      - `english_name` string, nullable
      - `native_name` string, nullable
      - `version` integer, nullable, required
      - `is_draft` boolean, required
    - `track` object
      - `id` string, required
      - `language` string, required
      - `english_name` string, nullable
      - `native_name` string, nullable
      - `version` integer, nullable, required
      - `is_draft` boolean, required
    - `match_status` 'resolved' | 'ambiguous' | 'not_found' | 'occurrence_not_found'
    - `match_count` integer: Total number of exact matches, including matches not present in this response page.
    - `matches` object[]: Exact matches only.
      - `text` string, required
      - `context` string, required
      - `start_ms` integer, required
      - `end_ms` integer, required
    - `matches_truncated` boolean
    - `next_occurrence` integer: The next one-based occurrence that can be requested when exact matches are truncated.
    - `suggestions` object[]: Fuzzy alternatives when no exact match exists. These are not exact matches.
      - `text` string, required
      - `context` string, required
      - `start_ms` integer, required
      - `end_ms` integer, required
    - `suggestions_truncated` boolean
    - `hint` string, nullable
    - `recovery` string

## Other responses

- `400`: Bad request
- `401`: Unauthorized, invalid or missing token
- `500`: Internal server error

## Changes

- **2026-11-03** `b86cb2a7b420`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/wistia/apis/data-api/changes/caption_matches/post.md)

---

[API](https://skmtc.dev/wistia/apis/data-api.md) - [All operations](https://skmtc.dev/wistia/apis/data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wistia/apis/data-api/revisions/b86cb2a7b420?raw)