TikTok Top Search API

TikTok Top Search

Features

• Find videos and image posts in one searchThe same keyword query can return video posts and photo carousels, with the type field identifying the format so you can keep both in one dataset or separate them for review.
• Choose the ordering and publication rangeSort matching content by relevance, publication date or likes and add a publication-time filter to focus the returned selection on the kind of content you want to inspect.
• Read the content together with its creator and countersEach result brings the caption, creator information, media links and available interaction counts together, so you can relate a post’s subject and format to the account that published it.

Parameters

How to Use

The request starts a background collection task, so its first response gives you a task ID rather than the finished data; use that ID to check progress and retrieve the results.

1. Enter a subject keyword, choose whether relevance, date or likes is most useful, and set a result limit; add a publication range or region only when you need those options.
2. Before running the example, replace $SOCQ_API_KEY with your own API key or set that environment variable. Send the JSON input to POST /v1/tiktok/top-search with the Authorization header shown below, then save the task_id from the response.
3. Use GET /v1/tasks/{task_id} with the saved ID to check progress. queued means waiting, running means collection is in progress, and retrying means another attempt is underway. Wait for succeeded before reading the results; if the task is failed, read error_message for the reason.
4. When the task succeeds, read data.results.items: each item in this list describes one video or photo-carousel post. An empty list means the task completed without returning any records.
5. If data.results.has_more is true, the next_cursor value is the marker for another page of saved results. Copy it unchanged into the cursor parameter of GET /v1/tasks/{task_id}?cursor=... and continue until has_more is false.

curl -X POST "https://api.socq.ai/v1/tiktok/top-search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","sort_by":"relevance","results_limit":20}'

Best Use Cases

• Build a topic-based content collection: Search a subject such as coffee, then save captions, creator handles, links and content types into a review table containing both video and image-post examples.
• Compare interaction counts across the returned posts: Combine the available likes, comments and shares with each post’s format and publication time to prepare a comparison sheet, keeping the query and filters so you know how the examples were selected.

Pro Tips

• When displaying a result, inspect type and media first: photo_carousel means an image post and should use an image gallery rather than a video player.
• When collecting several keywords, use the post ID to deduplicate repeated matches and keep the keyword associated with each collection so the same post is not counted several times by accident.
• If your workflow only accepts videos, use TikTok Search; if you need both videos and image posts, keep Top Search and handle both formats in your display.
• When a photo result has no duration or playback count, leave that measurement empty instead of interpreting it as a zero-second video or an unviewed post.

Related APIs