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

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).

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 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.

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.