TikTok API: Creator search and profiles

Creators are TikTok accounts indexed by Tokfluence, with stats, contact info, and cross-platform presence baked in.

GET`/v1/creators/search`#

Run the same filtered search the Tokfluence app uses. Results are paginated; per_page caps at 100.

Query parameters

Param	Type	Notes
`query`	string	Free text matched against usernames, tags, mentions, and bios. An exact or partial handle ranks first, so `query=mbellucci` finds `@mbellucci6`.
`niche_level`	string	How committed to the topic a creator must be. Governs both `query` and `hashtags[]` matching: `wide` (used the term once), `balanced` (self-identifies in bio or it recurs in top posts), `niche` (recurs in top post hashtags), `laser` (both). Defaults to `balanced`; pass `wide` for the previous broad behavior.
`min_followers`	int	Inclusive lower bound.
`max_followers`	int	Inclusive upper bound.
`min_engagement_rate`	float	0–1 fraction, matching the `engagement_rate` field in the response. e.g. `0.03` for 3%.
`regions[]`	string[]	ISO-3166 alpha-2 country codes (uppercase).
`gender`	string	`male`, `female`, `humans`, `no_face`, `artificial_intelligence`.
`brand`	bool	`true` returns brand/business accounts only; `false` excludes them. Omit to include both.
`is_tiktok_verified`	bool	Verified accounts only.
`has_email`	bool	Has a public contact email.
`has_phone`	bool	Has a contact phone number (parsed from the TikTok bio).
`hashtags[]`	string[]	Without the # prefix.
`mentions[]`	string[]	Without the @ prefix.
`has_youtube_linked`	bool	Has a discoverable YouTube channel.
`has_instagram_linked`	bool	Has a discoverable Instagram profile.
`sort`	string	`follower_count_desc`, `engagement_rate_desc`, `posts_per_week_desc`, `average_views_per_video_desc`, `last_analyzed_at_desc`, or any of these with `_asc`.
`page`	int	Defaults to 1. `page × per_page` cannot exceed 10,000 — see paging past 10,000.
`per_page`	int	Defaults to 20, max 100.
`cursor`	string	Switches to cursor pagination, which has no depth limit. Pass the `meta.next_cursor` from the previous response; omit on the first call.
`include`	string	Comma-separated extra embeds. Currently only `recent_posts`: pass `include=recent_posts` to embed each creator's latest posts. Off by default because it costs an extra lookup per page.

Example

bash

curl "https://developers.tokfluence.com/v1/creators/search?query=fitness&min_followers=50000&regions[]=US" \
  -H "Authorization: Bearer $TOKEN"

Response

json

{
  "data": [
    {
      "id": "tkc_a1b2c3d4e5f6a7b8",
      "username": "alice",
      "bio": "Daily home workouts.",
      "picture": "https://...",
      "region": "US",
      "verified": false,
      "brand": false,
      "gender": "female",

      "has_email": true,
      "contact_email": "alice@example.com",
      "contact_emails": ["alice@example.com", "press@alice.tv"],
      "has_phone": true,
      "contact_phone": "+15551234567",
      "contact_phones": ["+15551234567"],

      "follower_count": 142000,
      "average_views_per_video": 38000,
      "engagement_rate": 0.052,
      "posts_per_week": 4.2,
      "video_count": 240,
      "total_likes": 7500000,
      "audience_regions": [{"id": "US", "share": 0.62}],
      "last_analyzed_at": "2026-05-19T11:02:17.553Z",

      "hashtags": [{"value": "fitness", "count": 12}],
      "mentions": [{"value": "nike", "count": 3}],

      "youtube": {
        "subscribers": 12000,
        "channel_url": "https://youtube.com/@alice",
        "country": "US",
        "verified": true,
        "video_count": 90,
        "views": 4000000
      },
      "instagram": null
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 412,
    "total_pages": 21,
    "max_page": 500
  }
}

Paging past 10,000 results

Page-based paging reads the first 10,000 matches of a search. meta.max_page tells you where that ceiling falls at your page size; asking for a page beyond it returns 422 page_out_of_range rather than an empty list, so a truncated crawl is never mistaken for an exhausted one.

To read a result set larger than that, pass cursor instead of page. Each response carries a meta.next_cursor; feed it back to get the next slice. Results are ordered by your sort (default follower_count_desc) with a stable tiebreaker, so no creator is skipped or repeated across the walk. When next_cursor comes back null, you have reached the end.

bash

cursor=""
while :; do
  page=$(curl -sG "https://developers.tokfluence.com/v1/creators/search" \
    -H "Authorization: Bearer $TOKEN" \
    --data-urlencode "regions[]=BG" \
    --data-urlencode "min_followers=5000" \
    --data-urlencode "cursor=$cursor")

  echo "$page" | jq -r '.data[].username'

  cursor=$(echo "$page" | jq -r '.meta.next_cursor // empty')
  [ -z "$cursor" ] && break        # no cursor back = end of the result set
done

Cursor calls cost the same 1 credit per request as page-based calls, and each returns up to per_page creators.

Field reference

Param	Type	Notes
`id`	string	Stable Tokfluence creator id (`tkc_`).
`username`	string	Current TikTok username.
`bio`	string	Profile biography text.
`picture`	string	Profile picture URL.
`region`	string	ISO-3166 alpha-2, derived from creator location or top audience country.
`verified`	bool	TikTok verified badge.
`brand`	bool	`true` when the account is a brand/business rather than an individual creator.
`gender`	string	Inferred from profile picture (`male`, `female`, `no_face`, etc.).
`has_email`	bool	Whether any contact email is known. Useful as a filter without parsing the array.
`contact_email`	string	Primary contact email when known, else `null`.
`contact_emails`	string[]	All known contact emails, deduplicated.
`has_phone`	bool	Whether any contact phone is known. Useful as a filter without parsing the array.
`contact_phone`	string	Primary contact phone when known, else `null`.
`contact_phones`	string[]	All known contact phones, deduplicated.
`follower_count`	int	TikTok followers.
`average_views_per_video`	int	Mean views per video. `null` when we've analyzed fewer than 3 videos, since an average off one or two clips isn't meaningful.
`engagement_rate`	float	0–1, e.g. `0.052` = 5.2%. `null` when unknown or when the underlying sample yields an impossible (>100%) value.
`posts_per_week`	float	Posts per week. `0` is a real quiet period; `null` when we hold no posting cadence for the creator.
`video_count`	int	Total TikTok videos.
`total_likes`	int	Lifetime hearts across all videos.
`audience_regions`	object[]	Top audience countries with share.
`last_analyzed_at`	string	ISO 8601 timestamp of when we last refreshed this creator's rollup.
`hashtags`	object[]	Most-used hashtags, with frequency.
`mentions`	object[]	Most-used @-mentions, with frequency.
`youtube`	object	Linked YouTube channel info, or `null`.
`instagram`	object	Linked Instagram profile info, or `null`.
`recent_posts`	object[]	Up to 12 recent posts with stats (same shape as the posts endpoint). Always present on `GET /v1/creators/:id`; in search only when you pass `include=recent_posts`.

Contact details are included by default

No separate "reveal" call needed. The Developer plan covers contact visibility through your standard credit budget — every creators.search or creators.show response includes whatever emails and phone numbers we have on file. Use has_email=true or has_phone=true in search to narrow down to creators who actually have one.

GET`/v1/creators/:id`#

Fetch a single creator's profile. :id can be a TikTok username (e.g. wwe) or a Tokfluence creator ID (tkc_…). The response carries every search field plus a recent_posts array of the creator's latest posts.

bash

curl "https://developers.tokfluence.com/v1/creators/wwe" \
  -H "Authorization: Bearer $TOKEN"

GET`/v1/creators/:id/posts`#

Returns the creator's recent TikTok posts with stats, hashtags, mentions, and music metadata.

Query parameters

Param	Type	Notes
`limit`	int	Defaults to 24, max 50.

Live data — may take a few seconds

This endpoint hits TikTok via our proxy network on cold cache, so it costs 25 credits and can take a few seconds the first time you ask for a creator. On a warm cache it returns immediately. When the upstream needs to refresh stale data, the response is 202 with code: "analysis_pending" and a Retry-After header. You are not charged for the 202 — the credits come back. Retry after the suggested delay and the warm-cache hit will be billed normally.

bash

curl "https://developers.tokfluence.com/v1/creators/wwe/posts?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Creators

GET/v1/creators/search#

Query parameters

Example

Response

Paging past 10,000 results

Field reference

GET/v1/creators/:id#

GET/v1/creators/:id/posts#

Query parameters

GET`/v1/creators/search`#

GET`/v1/creators/:id`#

GET`/v1/creators/:id/posts`#