Trending videos

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: query is required, and the limit is 1–50 (default 10).

Search and browse

Production (flag off) requires query. The optional fields are platform, window, limit, region, summary_mode, download, and download_limit. Omit query only when the rebuild is on (api.dev, or the explicit flag).

Search trending TikTok videos

POST /v1/trending-videos/search

Required

query

Fields

Field	Notes
`platform`	MVP supports only `tiktok` (default).
`query`	Required in production. Brand, product, creator, or keyword (up to 200 chars). Omit it 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`. In production, the default for generic queries is `this-month`. The default for known SaaS profiles is `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. A browse without a region sends requests to the US, GB, and KR trending feeds.
`summary_mode`	`none` (default), `metadata`, or `transcript`. At this time, `transcript` returns metadata plus an unsupported warning.
`download` / `download_limit`	Reserved for a future mirror workflow. The MVP does not download or mirror videos. Values more than 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. The search does not use off-topic and stale hits to pad the results back to the requested limit. Production (flag off) keeps the legacy generic ranker, with 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. It does not include raw TikTok video CDN URLs.

The usual fields of a video entry are:

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 if the request omits query, and search in other cases. 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). It stays off on production www until NEXT_PUBLIC_SUME_COM_TRENDING_VIDEOS_UI_ENABLED is exactly 1 or true.

For the exact schema, refer to the live OpenAPI.

Pricing note

Each accepted call reserves and captures $0.10 USD of Sume usage. The same per-call price includes summary_mode: metadata. The cache can serve repeat browse calls, so that they do not hit ScrapeCreators again. Confirm the live price in GET /v1/catalog.

How this fits workflows

Use trending search for research. Then generate with Avatar / other generators, and use your own public HTTPS media inputs. Today, this endpoint does not return downloadable source files for face-swap or captions.