TikTok API: semantic creator search with natural language

Search influencers with natural language. Describe the kind of creator you want in plain English and get a ranked list back, best fit first. The phrase is embedded and matched semantically against the creator index, so results follow the meaning of your brief rather than exact keyword hits.

What it does

Embeds your natural-language phrase and matches it against a vector index of millions of TikTok creators.
Pulls the hard constraints it can see in the phrase (follower range, region) and applies them as filters on top of the semantic match.
Returns creators ranked by semantic fit, best first, each with a relative fit score.
Echoes the applied constraints in meta.constraints so you can see what it filtered on.
Uses the same creator schema as creators.search.

When to use this vs creators.search

Use semantic_search when your end-user describes intent in their own words ("wholesome cooking creators who feel like a friend"), where no fixed set of filters would capture the vibe. Use creators.search when your client already has explicit filters — it's 24 credits cheaper per call and answers in milliseconds.

POST`/v1/creators/semantic_search`#

Body

Param	Type	Notes
`query`required	string	Plain-English description of the creator you're looking for.
`max_results`	int	How many creators to return. Defaults to 20, max 50.
`min_followers`	int	Optional. Overrides any follower floor inferred from the phrase and narrows the vector search directly.
`max_followers`	int	Optional. Overrides any follower ceiling inferred from the phrase.
`region`	string	Optional. Two-letter region code (e.g. US). Overrides any region inferred from the phrase.

Example

bash

curl -X POST "https://developers.tokfluence.com/v1/creators/semantic_search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cozy home-cooking creators who feel like a friend in the kitchen, US based",
    "max_results": 5
  }'

Response shape

json

{
  "data": [
    {
      "id": "tkc_a1b2c3d4e5f6a7b8",
      "username": "alice",
      "follower_count": 78000,
      "engagement_rate": 0.078,
      "region": "US",
      "fit": 95,
      ...
    }
  ],
  "meta": {
    "constraints": {
      "region": "US"
    },
    "cost": 25
  }
}

The data array uses the same creator schema as creators.search (tkc_ id, contact emails, cross-platform info, etc.), plus a fit field per creator.

Fit score

Each creator carries a fit value from 1 to 95: how closely it matches this query, relative to the other results in the same response. The best match anchors near 95 and the rest scale down from there.

Fit is relative, not absolute

A vague phrase scores lower across the board than a specific one, so fit is only meaningful within a single response. Don't compare fit across different queries or use it as an absolute confidence threshold. Results are already returned best-first, so fit is mostly there to show your users a match strength.

Constraints the model applied

Every response includes meta.constraints: the hard filters the model pulled out of your phrase (follower range, region) and applied on top of the semantic match. It's empty when the phrase carried no filterable constraints. Anything you pass explicitly (min_followers, max_followers, region) wins over what the model infers and shows up here.

Latency and cost

This endpoint costs 25 credits per call and takes a couple of seconds: it embeds your phrase and runs a small LLM pass to extract constraints before the vector lookup.

Independent of the regular per-key throttle (1200 req/min), semantic search has its own ceiling: 30 calls per minute per key. Cache results client-side for repeated identical queries.

Errors

Param	Type	Notes
`200`	ok with data	Search ran, results returned. You're charged.
`200`	ok, empty	No creator matched the constraints. `data` is empty. You're still charged for the embedding and LLM pass.
`402`	insufficient_credits	Wallet empty. No search run.
`422`	missing_parameter	`query` is required and non-empty.
`502`	search_unavailable	The vector store or embedding service failed. Credits are refunded automatically.
`429`	rate_limited	30 calls/min/key cap reached. Retry after the `Retry-After` seconds.

Semantic search