---
title: "Celebrity Matches Search"
method: POST
path: "/api/v1/search/celebrity/matches"
tags: ["search > search"]
---

# Celebrity Matches Search

`POST /api/v1/search/celebrity/matches`

Find video frames that match a reference set of face images.Provide 15–100 upload IDs of reference images and get back ranked keyframe matches across the dataset's videos.

## Headers

- `Authorization` string, required

## Request body

- SearchCelebrityMatchesRequest — Celebrity matches request - searches for celebrity matches using a list of upload IDs
  - `dataset_id` string, uuid, required — The unique identifier for the dataset
  - `offset` integer — Starting index to return
  - `limit` integer — Max number of items to return
  - `metadata_filters` SearchMetadataFilters
    - `filters` SearchMetadataFiltersFiltersItems[], required
      - union
        - SearchBooleanEqualsClause
          - `key` string, required
          - `operator` '==', required
          - `value` boolean, required
        - SearchEqualsClause
          - `key` string, required
          - `operator` '==', required
          - `value` string, required
        - SearchNotEqualsClause
          - `key` string, required
          - `operator` '!=', required
          - `value` string, required
        - SearchDateTimeRangeInclusiveClause
          - `key` string, required
          - `start_utc_epoch` number, double, nullable
          - `end_utc_epoch` number, double, nullable
          - `operator` 'DateTimeRangeInclusive', required
  - `moderation_score_type` 'probability' | 'level' — Score type returned by the moderation service. - PROBABILITY: Scores in range 0-1 (uses BGE Reranker model) - LEVEL: Scores in range 0-5 (uses OpenAI model)
  - `upload_ids` string[], required — List of upload IDs to search for celebrity matches (15-100 items)

## Response `200`

Successful Response

- SearchNileSearchKeyframeResponse — A keyframe asset response from Nile for text to keyframe search
  - `data` SearchNileKeyframe[], required
    - `keyframe_id` string, uuid, required
    - `score` number, double, required
    - `asset_type` string, required
    - `dataset_id` string, uuid, required
    - `video_id` string, uuid, required
    - `composite_slice_id` string, uuid, nullable
    - `moderation_score` number, double, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-12** `3683abf6922b` — 1 info
  - api operation id `celebrity-matches-api-v-1-search-celebrity-matches-post` removed and replaced with `search_search_celebrity_matches_api_v1_search_celebrity_matches_post`
- **2026-08-22** `1223758be9ba` — 4 warning
  - the `limit` request property's max was set to `1000.00`
  - the `offset` request property's max was set to `9223372036854775808.00`
  - the `limit` request property's min was set to `1.00`
  - the `offset` request property's min was set to `0.00`

[Change history](https://skmtc.dev/coactive/apis/api-reference/changes/api/v1/search/celebrity/matches/post.md)

---

[API](https://skmtc.dev/coactive/apis/api-reference.md) · [All operations](https://skmtc.dev/coactive/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/coactive/apis/api-reference/revisions/3683abf6922b?raw)