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

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

The rebuilt browse feed (no-query default grid, higher limit, quality filters)
is **on for DEV** (`api.dev` / Railway `development`, and `www.dev` for the
Assets page). Production stays **OFF** until
`SUME_COM_TRENDING_VIDEOS_REBUILD_ENABLED` or
`NEXT_PUBLIC_SUME_COM_TRENDING_VIDEOS_UI_ENABLED` is exactly `1` or `true`.
Production keeps the legacy contract: required `query`, limit 1–50 (default 10).

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

## Search and browse

Production (flag off) requires `query`. Optional: `platform`, `window`,
`limit`, `region`, `summary_mode`, `download`, `download_limit`. Omit `query`
only when the rebuild is on (api.dev, or the explicit flag).

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

### Fields

| Field | Notes |
|---|---|
| `platform` | MVP supports only `tiktok` (default). |
| `query` | Required in production. Brand, product, creator, or keyword (up to 200 chars). Omit on api.dev or when `SUME_COM_TRENDING_VIDEOS_REBUILD_ENABLED` is on. |
| `window` | `yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`, `all-time`. Production generic queries default to `this-month`; known SaaS profiles default to `last-3-months`. |
| `limit` | Production: 1–50, default `10`. Rebuild flag on: 1–100, search default `20`, browse default `48`. |
| `region` | Optional two-letter country code. Browse without a region fans out across US, GB, and KR trending feeds. |
| `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. |

When the rebuild flag is on, search results must match the query (caption,
hashtag, mention, or author) and meet a minimum engagement floor. Off-topic
and stale hits are not padded back to the requested limit. Production (flag
off) keeps the legacy generic ranker: no extra relevance or view floor.

## Response shape

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

Typical video entry fields:

- `url` — canonical public TikTok watch URL
- `cover_url` — optional display thumbnail (not a downloadable video)
- `description`, `created_at`, `region`
- `author.handle` / `author.nickname`
- `metrics`, `relevance`, `scores`
- `summary` when `summary_mode` is not `none`

When the rebuild flag is on, `params.mode` is `browse` when `query` is omitted
and `search` otherwise. `params.cached` is `true` when the in-process feed
cache served the response. Production (flag off) omits these fields.

The Assets → Trending page (`/trending-videos`) is on for `www.dev` (when
`NEXT_PUBLIC_APP_URL` is the DEV host) and stays off on production www until
`NEXT_PUBLIC_SUME_COM_TRENDING_VIDEOS_UI_ENABLED` is exactly `1` or `true`.

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

## Pricing note

Each accepted call reserves and captures **$0.10 USD** of Sume usage.
`summary_mode: metadata` is included in the same per-call price. Repeat browse
calls may be served from cache so they do not re-hit ScrapeCreators. 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)