TikTok keyword search vs top search API: date_posted or publish_time

Use POST /v1/scrapecreators/tiktok_search_keyword when you want matches for a phrase and POST /v1/scrapecreators/tiktok_search_top when you want TikTok's top-results view of the same phrase. The two bodies are almost identical, but the time-window field has a different name: date_posted on keyword search, publish_time on top search, and the routes reject unknown arguments, so the wrong name returns 400 scrapecreators_invalid_input instead of being ignored.

Both are public social reads. They return media candidates (links and metadata), not video files hosted by Sume, and the OpenAPI description says there is no Sume credit charge in v1.

What the two request bodies share

Both routes require query (1 to 256 characters). Both accept sort_by, region, cursor, limit, max_pages and order. The window enum is the same on both: yesterday, this-week, this-month, last-3-months, last-6-months, all-time.

region is exactly two letters. cursor is an integer for these two routes, so keep the value the previous page gave you rather than inventing one. limit is 1 to 24 (default 10) and max_pages is 1 to 3 (default 3), which caps a single call at 24 returned items however many pages it reads.

A call that works

This asks for last week's most-liked matches for a phrase in the US. Swap the route and rename the window field to run the same search as top results.

curl -sS https://api.sume.com/v1/scrapecreators/tiktok_search_keyword \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"desk setup","date_posted":"this-week","sort_by":"most-liked","region":"US","limit":10}'

Reading the result

A terminal job inside the 30 second sync wait answers 200; otherwise you get 202 and continue on the job. Either way the body is data with operation, request_id, job, result and idempotency_hit.

order: play_count sorts the bounded sample locally. The OpenAPI text says it is not an all-time ranking, so do not present it as the most-played videos for the phrase. It is the most-played of at most 24 items from at most 3 pages.

Picking between keyword, top and trending

If you want a paid, production-oriented trend list with a fixed per-call price, that is the separate trending videos search at $0.10 per call. The two routes above are for ad hoc discovery where you pick the sort and window yourself. Run keyword search first for breadth, then top search when you want to see what TikTok ranks highest for the phrase, and compare the overlap before you commit a script to a hook.