POST /v1/trending-research: Reels and TikTok niche search over REST

POST https://api.sume.com/v1/trending-research takes a niche as query and returns a ranked list of public trending short videos from Instagram and TikTok, up to 24 per call. Each accepted search costs $0.10 USD, per the OpenAPI description (read 2026-10-10).

This is the REST route. The MCP tool of the same purpose has its own post, and the older POST /v1/trending-videos/search route is TikTok-only, as the Trending videos page states.

What can you send?

The body is strict, so unknown keys are rejected. All four fields are optional, but you need a niche from one of three places, and the first one present wins.

What comes back

The response is data with query, niche_source (typed, brand_category or brand_position), fetched_at, platforms, count, videos, warnings and optional usage. Check niche_source to see which input actually drove the search; if you sent only a category and expected a typed query, this is where you see it.

Each video has platform (tiktok or instagram), rank, id, url, a nullable cover_url, description, a nullable created_at, author.handle, author.nickname, and four counters in metrics: views, likes, comments and shares. YouTube is unsupported on this route. The sample prints the ranked list and any warnings:

import json, os, urllib.request

body = {"query": "home espresso", "limit": 6}
req = urllib.request.Request(
    "https://api.sume.com/v1/trending-research",
    data=json.dumps(body).encode(), method="POST",
    headers={"x-api-key": os.environ["SUME_API_KEY"], "User-Agent": "sume-example/1.0",
             "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=60) as r:
    data = json.load(r)["data"]

print(data["niche_source"], data["count"], data["platforms"])
for v in data["videos"]:
    m = v["metrics"]
    print(v["rank"], v["platform"], v["author"]["handle"], m["views"], v["url"])
for w in data["warnings"]:
    print("warning:", w["code"], w["message"])

What it is not

These are research rows with public watch URLs. The trending videos page says the MVP does not mirror downloadable source files, so do not feed a result URL into a route that needs a media file. To analyze a video scene by scene you would first need your own public HTTPS copy that you are allowed to use.

Treat warnings as part of the answer, not as noise: a call can succeed with a short list and a warning explaining why. Log them next to fetched_at so you can tell stale research from fresh.

• Budget $0.10 per accepted search, and cache by query in your own code.
• Do not send query and expect category to merge; the typed niche wins.
• Use limit 24 for a single broad pass instead of several narrow calls.

Budgeting the calls

Each accepted search costs $0.10, so the arithmetic is simple: 10 searches are $1.00, 100 are $10.00 and 1,000 are $100.00. The charge applies to accepted searches, so fix input errors before you loop; a bad limit (1 to 24 are valid) fails the request and teaches you nothing.

Plan the niche source deliberately. The endpoint takes the first of query, then category, then brand_position, so a request that carries all three is searched by query only. YouTube is not supported, so route those requests elsewhere instead of retrying them.