query_id_strstringrequired
Query ID, obtained from /tiktok/app-v3/creator-search-insights response
https://api.sandbase.ai/v1/api/tiktok/app-v3/creator-search-insights-detailGet detailed statistics for a TikTok Creator Search Insights query: popularity over time and audience breakdown by age, gender and country.
[
{
"data": {
"age": [
{
"category": "total",
"popularity": 433427
},
{
"category": "others",
"popularity": 330399
},
{
"category": "25-34",
"popularity": 49214
},
{
"category": "35+",
"popularity": 36110
},
{
"category": "18-24",
"popularity": 15704
},
{
"category": "16-17",
"popularity": 1400
},
{
"category": "4-15",
"popularity": 600
}
],
"demographics": {
"age": "25-34",
"gender": "unknown",
"location": "United Kingdom"
},
"extra": {
"latency": 34,
"logid": "202610061049214B1189B8169809B9F23D",
"now": 1791283761724,
"vgeo": "VGeo-US"
},
"gender": [
{
"category": "total",
"popularity": 493646
},
{
"category": "unknown",
"popularity": 439331
},
{
"category": "male",
"popularity": 29608
},
{
"category": "female",
"popularity": 24707
}
],
"location": [
{
"category": "total",
"popularity": 401003
},
{
"category": "United Kingdom",
"popularity": 159147
},
{
"category": "United States of America",
"popularity": 124437
},
{
"category": "Brazil",
"popularity": 34710
},
{
"category": "Pakistan",
"popularity": 13203
},
{
"category": "Nigeria",
"popularity": 8802
}
],
"status_code": 0,
"status_msg": ""
}
}
]Select an example to load its inputs and result into the playground.
Returns audience statistics for one TikTok Creator Search Insights query: popularity scores split by age, gender and country. It needs a query_id_str from the Creator Search Insights API and accepts an optional time range.
curl -X POST "https://api.sandbase.ai/v1/api/tiktok/app-v3/creator-search-insights-detail" \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query_id_str": "7449584484497752069", "time_range": "past_30_days"}'
The result is returned in outputs[0].data.
| Name | Type | Required | Description |
|---|---|---|---|
query_id_str | string | Yes | Query ID, obtained from /tiktok/app-v3/creator-search-insights response |
dimension_list | string | No | Dimension list, separated by comma, options: gender, age, country |
end_date | integer | No | End timestamp (seconds), only for custom range |
start_date | integer | No | Start timestamp (seconds), only for custom range |
time_range | string | No | Time range (past_7_days/past_30_days/past_60_days/past_6_months/custom) |
Real response for the request above, trimmed: lists keep their first item and long strings are cut.
{
"age": [
{
"category": "total",
"popularity": 355704
}
],
"demographics": {
"age": "25-34",
"gender": "unknown",
"location": "United Kingdom"
},
"extra": {
"latency": 44,
"logid": "2026110307435134E8D92AD0DB6B01A3B8",
"now": 1793691831842,
"vgeo": "VGeo-US"
},
"gender": [
{
"category": "total",
"popularity": 398818
}
],
"location": [
{
"category": "total",
"popularity": 324781
}
],
"status_code": 0,
"status_msg": ""
}
| Field | Meaning |
|---|---|
demographics.age / demographics.gender / demographics.location | Provider demographic summary. It is separate from bucket arrays and is not guaranteed to be the largest bucket including others/unknown. |
age[].category | Age bucket label such as 25-34. The list also holds total and others rows. |
age[].popularity | Reported popularity for an age bucket. The total belongs to this dimension and differs from gender/location totals; it is not a shared people count. |
gender[].category | Gender label such as male or unknown. The list also holds a total row. |
gender[].popularity | Popularity score for that gender value. |
location[].category | Country name such as United Kingdom. The list also holds a total row. |
location[].popularity | Popularity score for that country. |
status_code / status_msg | Call status. status_code is 0 and status_msg is empty when the call succeeds. |
query_id_str from the TikTok Creator Search Insights API.time_range accepts past_7_days, past_30_days, past_60_days, past_6_months or custom. Send start_date and end_date in seconds only with custom.dimension_list to a comma-separated mix of gender, age and country to choose which breakdowns you want.$0.001 per successful call. Failed calls are not charged. It is included in the daily free quota of each organization.
Send exact-string query_id_str. Choose time_range deliberately: past_7_days, past_30_days, past_60_days, past_6_months or custom are documented labels, but no default is declared. The saved example explicitly uses past_30_days. dimension_list is a comma-separated string of gender,age,country; custom alone uses integer start_date/end_date in seconds. There is no detail pagination input.
The October 7 saved query string matches the first August discovery record, but these independently dated examples are not a newly executed or time-consistent chain. The flat result contains age, gender, location and demographics, with no echoed query ID or time_range. Keep the requested ID and range in your own provenance; do not claim response identity matching that cannot be observed. Request country maps to response location.
Dimension arrays may be sparse or omitted. Validate present known arrays/objects and retain missing values as unknown. The saved totals differ: age 433427, gender 493646 and location 401003. These are reported popularity values, not verified person counts or a shared denominator. Do not add total rows to their buckets, assume exhaustive coverage or normalize every dimension by one total.
The saved demographics summary names age 25-34, but the age others bucket is larger. Gender unknown is also larger than the named gender buckets. Preserve the summary and arrays separately instead of claiming the summary is the largest group across all buckets or guessing unknown identities. Listed country buckets do not sum to location's total; do not invent a residual country to fill the gap.
The shortened README has different totals and is a separate undated reference, not evidence of growth against the full capture. Comparing time ranges or creating content recommendations requires a separately chosen task and compatible evidence; no second range, trend query or video analysis was executed. If you need candidate phrases first, choose one discovery page independently.
Choose one discovery page or one selected query detail. Give your agent the setup Skill, Markdown quickstart, endpoint and desired result. Keep SANDBASE_API_KEY locally and use POST /v1/api/ with Bearer authentication. Reading a candidate does not automatically authorize pagination, force refresh, trend/video enrichment or media retrieval.
Require completed SandBase status and an object at outputs[0].data, then integer status_code 0. Reject false, string 0 and missing status rather than returning an empty successful object. Saved status_msg is empty; no guessed success word is required. Keep optional fields and unknown values instead of manufacturing zero counts or reasons.
Pricing checked November 8 lists $0.001 per selected call, with 100 daily calls shared across eligible organization APIs and reset at 00:00 UTC. Eligibility is not remaining allowance. Two deliberate requests list at $0.002 before quota effects; the code does not execute a pair automatically. Response cost_tracker and extra.latency are provider fields, not SandBase billing or a measured performance benchmark. No new business, paid, continuation or media call was made. The Creator Search Insights Python guide contains the dated October experiment; use the current request boundaries described here.
Start building
Platform API endpoint with unified authentication and usage tracking.
# The quoted heredoc keeps Unicode and shell metacharacters unchanged.
result=$(curl --fail-with-body --silent \
-X POST "https://api.sandbase.ai/v1/api/tiktok/app-v3/creator-search-insights-detail" \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'SANDBASE_JSON'
{
"query_id_str": "7449584484497752069",
"time_range": "past_30_days"
}
SANDBASE_JSON
)
printf '%s\n' "$result"Set your SandBase API key in your server environment. Requests use Bearer authentication.
export SANDBASE_API_KEY="YOUR_API_KEY"Keep your key on the server. Do not expose it in browser code.
query_id_strstringrequiredQuery ID, obtained from /tiktok/app-v3/creator-search-insights response
dimension_liststringDimension list, separated by comma, options: gender, age, country
end_dateintegerEnd timestamp (seconds), only for custom range
start_dateintegerStart timestamp (seconds), only for custom range
time_rangestringTime range (past_7_days/past_30_days/past_60_days/past_6_months/custom)
Saved example response for this API; no live request is made when viewing it.
[
{
"data": {
"age": [
{
"category": "total",
"popularity": 433427
},
{
"category": "others",
"popularity": 330399
},
{
"category": "25-34",
"popularity": 49214
},
{
"category": "35+",
"popularity": 36110
},
{
"category": "18-24",
"popularity": 15704
},
{
"category": "16-17",
"popularity": 1400
},
{
"category": "4-15",
"popularity": 600
}
],
"demographics": {
"age": "25-34",
"gender": "unknown",
"location": "United Kingdom"
},
"extra": {
"latency": 34,
"logid": "202610061049214B1189B8169809B9F23D",
"now": 1791283761724,
"vgeo": "VGeo-US"
},
"gender": [
{
"category": "total",
"popularity": 493646
},
{
"category": "unknown",
"popularity": 439331
},
{
"category": "male",
"popularity": 29608
},
{
"category": "female",
"popularity": 24707
}
],
"location": [
{
"category": "total",
"popularity": 401003
},
{
"category": "United Kingdom",
"popularity": 159147
},
{
"category": "United States of America",
"popularity": 124437
},
{
"category": "Brazil",
"popularity": 34710
},
{
"category": "Pakistan",
"popularity": 13203
},
{
"category": "Nigeria",
"popularity": 8802
}
],
"status_code": 0,
"status_msg": ""
}
}
]Explore more
| API | Price | Response |
|---|---|---|
TikTok | $0.001 per call | JSON |
TikTok | $0.001 per call | JSON |
TikTok | $0.01 per call | JSON |
TikTok | $0.001 per call | JSON |
TikTok | $0.001 per call | JSON |
TikTok | $0.001 per call | JSON |
Questions
Send a POST request to https://api.sandbase.ai/v1/api/tiktok/app-v3/creator-search-insights-detail with your SandBase API key in the Authorization header (Bearer) and the parameters as a JSON body. You can also try it in the Playground on this page without writing code.
$0.001 per call. Every organization gets 100 free calls per UTC day, shared across eligible SandBase APIs including this one; after that each call is billed at this price from your SandBase balance. There is no subscription.
Required: query_id_str (string). Optional: dimension_list (string), end_date (integer), start_date (integer) and time_range (string). The Parameters table and the Playground on this page list every field.
A JSON response returned in the same HTTP request (synchronous). The README on this page includes a sample response.
No. TikTok Creator Search Insights Detail runs through SandBase, so one SandBase API key covers this endpoint and every other API and model in the catalog. You do not need to apply for TikTok API access separately.
The schema declares no time_range default; the saved request deliberately selects past_30_days. Its result does not echo query_id_str or time_range. Store your chosen request context; do not invent a response identity check.
No. Saved age, gender and location totals differ. These are provider popularity values, not verified person counts or a common denominator. Keep total separate from bucket rows, and do not invent missing country buckets or zero-valued dimensions.
Not unconditionally. The saved summary says 25-34, while the others age bucket is larger. Unknown gender stays unknown. Preserve summary and bucket data separately; a single reference does not prove audience fit or a current growth trend.