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 answers in milliseconds, with no embedding or LLM pass.

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

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 takes a couple of seconds: it embeds your phrase and runs a small LLM pass to extract constraints before the vector lookup. A search call costs 1 credit, plus 1 per profile with contact details it returns. Profiles without contact details are free, and nothing is charged when no creator matches. meta.cost holds the credits this call charged.

Semantic search has no contact filter. To pay only for creators you can reach, or only for the call, run the same niche through creators.search with has_email.

If your balance cannot cover every profile with contact details, you still get all max_results. The ones it could not pay for come back without their contact values, and meta.billing says so: unit, credits_charged, rows_with_contacts, rows_with_contacts_charged, capped_by_balance and note. At a balance of 0 the call returns 402 insufficient_credits. Creators removed by the stated-minors filter are neither served nor charged. See search billing.

Semantic search shares the per-key limit of 120 requests per minute with every other /v1 and /mcp endpoint. Cache results client-side for repeated identical queries.

Errors

Param	Type	Notes
`200`	ok with data	Search ran, results returned. You're charged 1 credit for the call, plus 1 per profile with contact details.
`200`	ok, empty	No creator matched the constraints. `data` is empty. Nothing is charged.
`402`	insufficient_credits	Wallet empty (balance 0). 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	The 120 requests/min/key cap was reached. Retry after the `Retry-After` seconds.

Semantic search