Request captions with the posts
Send platforms=tiktok and include=metadata,transcript to POST /api/public/social-posts. Available captions are reused or retrieved automatically. This is topic-based discovery, not a promise to transcribe any arbitrary video URL. Some videos have no available native captions, and video files are not downloaded.
Read timing, language and truncation
Where available, transcript includes language, language_code, is_generated, segments, total_segments and truncated. Segment start and duration are seconds. A response can be bounded to 2,000 source segments, 4,000 characters per segment and 100,000 text characters total. Check truncated before presenting a transcript as complete.
Budget for successful caption delivery
Newly retrieved TikTok native captions cost 0.3 credit each when successfully delivered, in addition to fresh-post charges. Unavailable, cached, errored and undelivered captions are free. For up to 20 fresh TikTok posts with new captions, the example reserves a maximum of seven credits: one for posts plus six for captions.
Control the request and budget
Send a topic in term and set limit from 1 to 100. Optional start and end use UTC ISO dates: start is inclusive and end is exclusive, with a maximum 31-day window. Omit dates for the last seven days. Set max_credits before sending. Cached results and cursor pages cost zero credits.
Wait for the result, then paginate
A cached result can return immediately. A fresh request can return HTTP 202 with data.status=processing. Save data.id and poll GET /api/public/social-requests/{id} every five seconds with a finite deadline. Polling is free. Follow next_cursor with unchanged filters and a new Idempotency-Key per page. Reuse the original key and exact body after an uncertain network failure.
Understand the coverage
Results come from collected public web data and are samples, not a complete or representative census. Missing posts do not prove that a topic has no activity. Preserve source URLs and collection context when presenting results. Optional fields can be absent; this is not an official platform API.
Request TikTok posts and available captions
Example requests require your own API key. Running a request can consume prepaid credits within the stated budget.
# Save this ID and body before sending; reuse both on uncertain retries.
REQUEST_ID=$(uuidgen)
curl 'https://social.tickertrends.io/api/public/social-posts' \
-H "X-API-Key: $TICKERTRENDS_API_KEY" \
-H "Idempotency-Key: $REQUEST_ID" \
-H 'Content-Type: application/json' \
--data '{"term":"openai","platforms":"tiktok","limit":20,"include":"metadata,transcript","max_credits":7}'
# If data.status is processing, replace RETURNED_REQUEST_ID with data.id.
# This is the server receipt ID, not the Idempotency-Key. Poll every 5 seconds:
curl 'https://social.tickertrends.io/api/public/social-requests/RETURNED_REQUEST_ID' \
-H "X-API-Key: $TICKERTRENDS_API_KEY"