List a TikTok creator's recent videos: handle, user_id and play_count

To list one creator's recent TikTok videos on Sume, call POST /v1/scrapecreators/tiktok_videos with their handle. The result is a sample of at most 24 items from at most 3 pages, and order: play_count sorts that sample, so it is not the creator's most-viewed videos of all time.

That distinction matters if you are building a swipe file or a competitor report: the honest label for the output is 'most played in the latest sample'.

Handle, user_id and profile

tiktok_videos requires handle. A leading @ is stripped, and the handle must match ^@?[A-Za-z0-9._]{1,30}$. It also accepts user_id, max_cursor for paging and region. tiktok_profile is the sibling route for account metadata and accepts either handle or user_id.

Anything outside that shape, including a full profile URL, is a 400 scrapecreators_invalid_input. Strip the URL to its handle in your own code first.

Request and paging

The first call needs only the handle. For the next page, send the cursor the previous result returned as max_cursor; do not construct one. max_pages of 1 gives the cheapest and fastest single page, and the default of 3 reads up to three before the 24-item cap applies.

curl -sS https://api.sume.com/v1/scrapecreators/tiktok_videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"@example.creator","limit":12,"max_pages":2,"order":"play_count"}'

What to do with the candidates

The items are links and metadata. To analyze one, pass its URL to the media import route first, since the import is what puts a copy in Sume storage, at a fixed $0.15 estimate per accepted import. The route itself has no Sume credit charge in v1, though the upstream request uses vendor credits, so keep max_pages low in loops.

For a 202 after the 30 second sync wait, follow the returned job rather than re-sending the same body.