---
title: "Search the TikTok creators dataset"
method: GET
path: "/datasets/creators/search"
tags: ["Datasets"]
---

# Search the TikTok creators dataset

`GET /datasets/creators/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/datasets/creators/search`
- Auth: API key in header `x-api-key`

Searches TikTok creators stored in a search index (one document per creator), with follower counts, verified status, niche, and engagement. Deleted and private accounts are excluded by default; set `include_inactive=true` to include them for historical lookups. Sort enum: `followers_desc`, `engagement_desc`, `engagement_qualified_desc`, `likes_desc`, `relevance`. Coverage note: `followers_desc`, `likes_desc`, and `relevance` are backed by profile fields present across the full dataset; the post-level engagement metrics (`engagement_rate`, `avg_views`, and the nested `post_stats` object) and the `engagement_desc`/`engagement_qualified_desc` sorts are currently populated for a growing subset of creators, prioritizing the highest-reach accounts. Creators without these metrics are still returned but sort last under `engagement_desc` and omit those fields; `engagement_qualified_desc` excludes them outright (they cannot clear its floors). `engagement_desc` ranks by raw `engagement_rate` with no eligibility floor — it surfaces a real stale-record + ratio-by-design trap: an account whose last real post was years ago can still carry an unrealistic rate computed from a handful of old posts. `engagement_qualified_desc` is the same metric restricted to creators with a recent post (`last_post_at` within 90 days), a minimum reach (`avg_views >= 10000`) and sample size (`post_stats.sampled_posts >= 10`), and a sanity ceiling (`engagement_rate <= 50%`) — use this, not the raw sort, for a "best engagement" leaderboard. Sound fields: `post_stats.top_sounds` holds only a creator's FIVE most-used sounds from the sampled posts, ranked by use count with ties broken by lowest `music_id`, so it is a top-5 view and not the creator's full sound list; `post_stats.distinct_sounds` gives the true number of different sounds the sample used. Use each sound's `original` boolean to tell TikTok-generated original audio from catalogue tracks - do NOT infer it from the title, because TikTok localizes the original-audio label (`sonido original`, `som original`, `оригинальный звук`, and at least fifteen more), so a title match silently reclassifies original audio as named tracks. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100).

## Query parameters

- `q` string
- `handle` string
- `niche` string
- `country` string
- `verified` boolean
- `min_followers` integer
- `has_email` boolean
- `include_email` boolean
- `include_inactive` boolean
- `sort` 'followers_desc' | 'engagement_desc' | 'engagement_qualified_desc' | 'likes_desc' | 'relevance'
- `page` integer
- `page_size` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- DatasetsCreatorsSearchResponseDoc
  - `code` integer
  - `data` DatasetsCreatorsSearchResponse
    - `dataset` string: Identifier of the dataset queried (`creators`).
    - `items` EsCreatorRecord[]: Matching creator records on this page.
      - `avatar_url` string: URL of the profile picture.
      - `avg_views` integer: top-level mirror of PostStats.AvgViews for sort/filter
      - `bio` string: Profile biography text.
      - `bio_link` string: Link shown in the profile biography.
      - `brand_affiliations` string[]: Brands linked to the creator.
      - `country` string: Creator's country or region code in lowercase, for example `us`.
      - `creator_uid` string: Unique creator id, made of the platform and the handle, for example `tiktok:@bubble`.
      - `email` string: Business contact email found for the creator.
      - `email_status` string: Verification status of the contact email.
      - `engagement_rate` number: headline = by-view (TikTok standard); see PostStats for both
      - `first_seen` string: FirstSeen is the discovery timestamp: set once when the creator is first indexed, and never changed by a later re-crawl. Values recorded before 2026-08-29 are unreliable and should not be used for cohort or tenure analysis.
      - `follower_count` integer: Number of followers.
      - `following_count` integer: Number of accounts the creator follows.
      - `language` string: Language code set on the creator's profile.
      - `last_crawled` string: Time the creator's profile was last fetched, in UTC (RFC 3339).
      - `last_post_at` string: top-level mirror of PostStats.LastPostAt for recency filter
      - `niche` string: Niche is the DISCOVERY SEED TERM that surfaced this creator (the keyword/hashtag/ explore-category the crawler used), NOT a content classification. It is single-valued and first-write-wins, so a creator found via the "korean skincare" keyword sweep is tagged "skincare" whatever they actually post about. Do not present it as a category; use NicheClassified for that.
      - `niche_classified` string: NicheClassified is the content niche DERIVED FROM THE BIO by classifyNiche() in the creatorsdb-enrich worker. Independent of Niche by construction: it is computed for every creator with a bio, including those that already carry a seed term, so the two fields never contaminate each other and "which is this?" is answered by the field name rather than an unbackfillable provenance flag.
      - `nickname` string: Display name shown on the creator's profile.
      - `platform` string: Social platform the creator is on, for example `tiktok`.
      - `post_stats` EsPostStatsAgg
        - `analyzed_at` string: Time these post statistics were calculated, in UTC (RFC 3339).
        - `avg_comments` integer: Average comment count per sampled post.
        - `avg_likes` integer: Average like count per sampled post.
        - `avg_saves` integer: Average save (bookmark) count per sampled post.
        - `avg_shares` integer: Average share count per sampled post.
        - `avg_video_duration_sec` number: Average video length of sampled posts, in seconds.
        - `avg_views` integer: Average view count per sampled post.
        - `best_post_id` string: TikTok identifier of the most viewed sampled post.
        - `best_post_views` integer: View count of the most viewed sampled post.
        - `distinct_sounds` integer: DistinctSounds is how many different sounds the sampled posts used. TopSounds keeps only the five most-used, so without this a consumer cannot tell a creator who reuses one sound across the sample from one who used a different sound every time — both surface five rows.
        - `engagement_rate_by_follower` number: Average over sampled posts of likes, comments and shares divided by the creator's follower count, as a fraction.
        - `engagement_rate_by_view` number: Likes, comments, shares and saves divided by views across sampled posts, as a fraction (0.05 means 5%).
        - `first_post_at` string: Time of the oldest sampled post, in UTC (RFC 3339).
        - `last_post_at` string: Time of the most recent sampled post, in UTC (RFC 3339).
        - `median_likes` integer: Median like count across sampled posts.
        - `median_views` integer: Median view count across sampled posts.
        - `original_sound_ratio` number: Share of sampled posts that use the creator's own original sound, as a fraction from 0 to 1.
        - `posts_per_week` number: Average number of posts per week between the oldest and newest sampled post.
        - `sampled_posts` integer: Number of the creator's recent posts included in these figures.
        - `top_hashtags` string[]: Most used hashtags across sampled posts, lowercase and without the leading `#`, most used first.
        - `top_sounds` EsPostSound[]: Most used sounds across sampled posts, most used first.
          - `author` string: Name of the account or artist credited for the sound.
          - `music_id` string: TikTok identifier of the sound.
          - `original` boolean: Original marks TikTok-generated original audio. Titles cannot be used for this: TikTok localizes the label (`sonido original`, `оригинальный звук`, …), so a title match silently reclassifies original audio as a named track.
          - `title` string: Title of the sound as TikTok shows it.
          - `uses` integer: Number of the creator's sampled recent posts that used this sound.
        - `views_to_follower_ratio` number: Average views per sampled post divided by the creator's follower count.
      - `sec_uid` string: Stable account id the platform assigns to the creator.
      - `source` string: Label for where the creator entry came from.
      - `status` string: "" active | "deleted" | "private" — refresh marks these to skip future crawls
      - `total_likes` integer: Total likes received across the creator's videos.
      - `unique_id` string: Creator's handle on the platform, without the `@`.
      - `verified` boolean: Whether the profile has the platform's verified badge.
      - `video_count` integer: Number of videos posted.
    - `page` integer: Page number returned.
    - `page_size` integer: Number of items per page.
    - `sort` string: Sort order applied.
    - `total` integer: Total number of records matching the filters.
  - `msg` string

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)