---
title: Trending videos
description: Search TikTok trending video metadata for brand, product, creator, or keyword research.
---

Trending video search returns ranked public TikTok video **metadata** for a
query. It is a paid research utility, not a generation model.

```text
POST /v1/trending-videos/search
```

## Search

Required: `query`. Optional: `platform`, `window`, `limit`, `region`,
`summary_mode`, `download`, `download_limit`.

<!-- api-call-example:trending-videos-search -->

### Fields

| Field | Notes |
|---|---|
| `platform` | MVP supports only `tiktok` (default). |
| `query` | Brand, product, creator, or keyword (1-200 chars). |
| `window` | `yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`, `all-time`. Known SaaS profiles default to `last-3-months`; other queries default to `this-month`. |
| `limit` | 1-50, default `10`. Known-profile filters may return fewer. |
| `region` | Optional two-letter country code. |
| `summary_mode` | `none` (default), `metadata`, or `transcript`. `transcript` currently returns metadata plus an unsupported warning. |
| `download` / `download_limit` | Reserved for a future mirroring workflow. MVP does not download or mirror videos; values above zero return an unsupported warning. |

## Response shape

The response includes ranked videos with public watch URLs, author handles,
metrics, relevance scores, and optional lightweight summaries — not raw TikTok
CDN media URLs.

Typical video entry fields:

- `url` — canonical public TikTok watch URL
- `description`, `created_at`, `region`
- `author.handle` / `author.nickname`
- `metrics`, `relevance`, `scores`
- `summary` when `summary_mode` is not `none`

Exact schema: live [OpenAPI](https://api.sume.com/reference/json).

## Pricing note

Each accepted search reserves and captures **$0.10 USD** of Sume usage.
`summary_mode: metadata` is included in the same per-search price. Confirm live
pricing in `GET /v1/catalog`.

## How this fits workflows

Use trending search for research, then generate with Avatar / other generators
using your own public HTTPS media inputs. Do not expect this endpoint to return
downloadable source files for face-swap or captions today.

## Related

- [Generate avatar video](/models/avatar-videos)
- [Face swap (Beta)](/models/face-swap)
- [Video captions](/models/video-captions)
- [API recipes](/api/cookbook)