TikTok Research API documentation: 30-day dates vs Sume date_posted
The Research API takes start_date and end_date up to 30 days apart. Sume's tiktok_search_keyword takes one fixed date_posted value instead.
The TikTok Research API Query Videos page says the end_date must be no more than 30 days after the start_date, so you pass an explicit date pair. Sume's tiktok_search_keyword has no date pair: date_posted is one of six fixed values, and you choose the nearest one.
TikTok facts are from its Query Videos page (updated September 1, 2026); Sume facts from the OpenAPI document behind the API reference and the trending videos docs, read 2026-09-30.
What date rule does the Research API state?
One quoted rule: "The end_date must be no more than 30 days after the start_date". A longer span means several queries, each with its own pair. The page also lists a region_code filter with two-letter country codes such as US, JP, GB and FR.
Which windows can tiktok_search_keyword take?
| Need | Research API input | Sume tiktok_search_keyword |
|---|---|---|
| Last day | Pair 1 day apart | date_posted: "yesterday" |
| Last week | Pair 7 days apart | "this-week" |
| Last month | Pair up to 30 days apart | "this-month" |
| Last 3 months | Several 30-day queries | "last-3-months" |
| Last 6 months or all time | Several 30-day queries | "last-6-months" or "all-time" |
How do I convert a start and end date?
Pick the smallest value that covers your start date, then filter the returned items by their own post time on your side. The route also has sort_by (relevance, most-liked, date-posted) and an optional two-letter region. The window names match the ones in the trending videos docs, but that is a separate route; see yesterday vs this-month on trending search.
Is there any way to pin exact dates?
Not on this route: the schema has no start or end field, and it rejects unknown fields (additionalProperties: false). If exact date boundaries matter for a study, the Research API is the surface that supports them. For recent public video discovery with a bounded result of at most 24 items, the fixed window is enough.
Sources
Related posts
More in Developers
- Join voiceover clips inside one timeline render with audio.parts
Timeline 1.0 takes up to 20 gapless audio.parts slices with source_in and duration. Skip the timeline-audio job when the join is only for one render.
- Timeline 1.0 limits: 200 slots, 1800 s, 20 audio parts, 8 fades
The numbers that cap one Timeline 1.0 render: 1 to 200 video slots, 1 to 1800 s of audio, 20 audio parts, 12-slot single strategy and 8 chained fades.
- Timeline render warnings: padded or looped short sources explained
A Timeline 1.0 slot longer than its source renders with a soft warning, not a failure, and /plan cannot predict it. Read warnings[] and probe clips first.
- Token bucket vs fixed window: what a reset header means
Anthropic says its limits replenish continuously; Sume's docs call ratelimit-reset the seconds until the window resets. How to pace a client for each.
Written by Sume