TikTok Creator Search Insights Detail

API docs
https://api.sandbase.ai/v1/api/tiktok/app-v3/creator-search-insights-detail

Get detailed statistics for a TikTok Creator Search Insights query: popularity over time and audience breakdown by age, gender and country.

Price
$0.001USD / call
Method
POST
Response
JSON
Parameters
1 required · 4 optional
100 free calls / dayFirst 100 calls per day free (shared per organization) · Resets at 00:00 UTC. Pay per call after that.

Playground

Input
Query ID, obtained from /tiktok/app-v3/creator-search-insights response
Dimension list, separated by comma, options: gender, age, country
End timestamp (seconds), only for custom range
Start timestamp (seconds), only for custom range
Time range (past_7_days/past_30_days/past_60_days/past_6_months/custom)
OutputExample
Responseoutputs · 1.8 KB · 93 lines
[
  {
    "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": ""
    }
  }
]

Examples

Select an example to load its inputs and result into the playground.

API README

TikTok Creator Search Insights Detail API

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.

Use cases

  • Check which age groups search for a topic before planning a video.
  • Inspect reported gender popularity buckets while preserving unknown; these are not verified population shares.
  • Inspect reported location popularity fields; they do not independently determine a posting language or target region.
  • Choose one explicit time range; comparison across ranges is a separate task and no audience-change experiment was performed here.

Request

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.

Parameters

NameTypeRequiredDescription
query_id_strstringYesQuery ID, obtained from /tiktok/app-v3/creator-search-insights response
dimension_liststringNoDimension list, separated by comma, options: gender, age, country
end_dateintegerNoEnd timestamp (seconds), only for custom range
start_dateintegerNoStart timestamp (seconds), only for custom range
time_rangestringNoTime range (past_7_days/past_30_days/past_60_days/past_6_months/custom)

Example response

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": ""
}

Response fields

FieldMeaning
demographics.age / demographics.gender / demographics.locationProvider demographic summary. It is separate from bucket arrays and is not guaranteed to be the largest bucket including others/unknown.
age[].categoryAge bucket label such as 25-34. The list also holds total and others rows.
age[].popularityReported 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[].categoryGender label such as male or unknown. The list also holds a total row.
gender[].popularityPopularity score for that gender value.
location[].categoryCountry name such as United Kingdom. The list also holds a total row.
location[].popularityPopularity score for that country.
status_code / status_msgCall status. status_code is 0 and status_msg is empty when the call succeeds.

Notes

  • Get 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.
  • Set dimension_list to a comma-separated mix of gender, age and country to choose which breakdowns you want.
  • For the popularity trend of a query over time, see TikTok Creator Search Insights Trend.

Pricing

$0.001 per successful call. Failed calls are not charged. It is included in the daily free quota of each organization.

Inspect one selected query's demographic fields

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.

Give your agent one search-insights task

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.

Explore more

Related APIs

All APIs
APIPriceResponse
TikTok$0.001 per callJSON
TikTok$0.001 per callJSON
TikTok$0.01 per callJSON
TikTok$0.001 per callJSON
TikTok$0.001 per callJSON
TikTok$0.001 per callJSON

Questions

FAQ

How do I use the TikTok Creator Search Insights Detail API?

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.

How much does the TikTok Creator Search Insights Detail API cost?

$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.

What parameters does the TikTok Creator Search Insights Detail API accept?

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.

What does the TikTok Creator Search Insights Detail API return?

A JSON response returned in the same HTTP request (synchronous). The README on this page includes a sample response.

Do I need a TikTok developer account or API key?

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.

Is past_30_days a default and does the result echo the query ID?

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.

Can all demographic dimensions use one total for percentages?

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.

Does the demographics summary identify the largest bucket?

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.