Discover creators

Searches TikTok’s Creator Marketplace by filters and returns one page of creators, in TikTok’s order. Use it to find creators the shop hasn’t worked with yet. Each row has openId (use it for invites and DMs), username, followers, average shoppable views, GMV (precise gmv only when the creator shares it, else gmvRange), unitsSoldRange, top follower demographics and a profile block.

Send filters in the JSON body: keyword (matches username and nickname only), followers (count, age ranges, gender share in basis points), gmvRanges and unitsSoldRanges (TikTok’s four fixed buckets), categories, contentPerformance, affiliate (commission, post rate, agency status, fast-growing, not invited in 90 days) and advanced (region options and sort order from Discovery filters). All metrics cover the last 30 days. pageSize is 12 or 20. Unknown keys are rejected.

To page, pass nextPageToken back as pageToken along with searchKey. hasMore is false on the last page. Each call spends TikTok marketplace search quota, so Growi applies a per-shop daily cap (2,000 by default, reset at 00:00 UTC), and the quota block shows what’s left. TikTok sometimes returns thin pages, so a short page doesn’t mean the market is empty.

POST /tik_tok_shop/creators/discover

Discover creators

cURL

curl --request POST \
  --url https://api.growi.io/api/public/v1/tik_tok_shop/creators/discover \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "keyword": "skincare",
  "pageSize": 20,
  "followers": {
    "countMin": 10000,
    "countMax": 100000,
    "ageRanges": [
      "AGE_RANGE_18_24",
      "AGE_RANGE_25_34"
    ],
    "gender": {
      "gender": "FEMALE",
      "minShareBp": 6000
    }
  },
  "gmvRanges": [
    "GMV_RANGE_1000_10000",
    "GMV_RANGE_10000_AND_ABOVE"
  ],
  "categories": [
    {
      "parentCategoryId": "600001",
      "childCategoryIds": [
        "851848"
      ]
    }
  ],
  "contentPerformance": {
    "avgShoppableVideoViewsMin": 5000,
    "avgEngagementRateMin": 3
  },
  "affiliate": {
    "postRate": "GOOD",
    "notInvitedLast90Days": true
  },
  "advanced": {
    "sorterAlgorithmId": "1"
  }
}
'

200

{
  "creators": [
    {
      "openId": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg",
      "username": "glowwithmia",
      "nickname": "Mia",
      "avatarUrl": "https://p16-sign.tiktokcdn-us.com/avatar.jpeg",
      "selectionRegion": "US",
      "categoryIds": [
        "600001"
      ],
      "followerCount": 48200,
      "avgShoppableVideoViews": 6100,
      "avgShoppableLiveViewers": null,
      "gmv": null,
      "videoGmv": null,
      "liveGmv": null,
      "gmvRange": {
        "min": "1000",
        "max": "10000",
        "formatted": "$1K-$10K",
        "currency": "USD"
      },
      "unitsSoldRange": {
        "min": 100,
        "max": 1000,
        "formatted": "100-1K"
      },
      "topFollowerDemographics": {
        "ageRanges": [
          "AGE_RANGE_18_24",
          "AGE_RANGE_25_34"
        ],
        "majorGender": {
          "gender": "FEMALE",
          "percentageBp": 7120
        }
      },
      "profile": {
        "ppsScore": "4.4",
        "creatorLevel": 3,
        "isFastGrowing": true,
        "isRisingStar": false,
        "isOfficialRecommend": false,
        "hasCollaborated": false,
        "hasInvitedLast90Days": false,
        "isBlockedByShop": false,
        "isEligibleFlatFee": true,
        "mcnName": null,
        "userTypeTags": []
      }
    }
  ],
  "nextPageToken": "b2Zmc2V0PTIw",
  "searchKey": "2E+0EcXoSk2HWdEWh2nITfkBRMbwuug0mt9s3fWgV0k=",
  "hasMore": true,
  "quota": {
    "scope": "gateway_discover_daily",
    "limit": 2000,
    "used": 14,
    "remaining": 1986,
    "resetsAt": "2026-09-30T00:00:00.000Z"
  },
  "persisted": false
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

organization_id · integer

Use the TikTok Shop of this child brand (organization id) of your API key's organization

Body

application/json

keyword · string

Matches TikTok username and nickname only. Not a topic or semantic search.

Maximum string length: 100

pageSize · enum<integer> · default: 20

TikTok accepts only 12 or 20.

Available options: 12, 20

pageToken · string

nextPageToken from the previous page. Omit on the first page.

searchKey · string

searchKey from the previous page. Pass it back so TikTok serves a stable result set across pages.

followers · object

Audience filters: ageRanges (TikTok's age buckets), countMin and countMax (follower count, countMin must not exceed countMax), and gender ({ gender, minShareBp }, the minimum share of that gender in basis points, 6000 = 60%).

Show child attributes

gmvRanges · enum<string>[]

TikTok's four fixed 30-day GMV buckets. Several buckets cover their union.

Minimum array length: 1

Available options: GMV_RANGE_0_100, GMV_RANGE_100_1000, GMV_RANGE_1000_10000, GMV_RANGE_10000_AND_ABOVE

unitsSoldRanges · enum<string>[]

TikTok's four fixed units-sold buckets.

Minimum array length: 1

Available options: UNITS_SOLD_RANGE_0_10, UNITS_SOLD_RANGE_10_100, UNITS_SOLD_RANGE_100_1000, UNITS_SOLD_RANGE_1000_AND_ABOVE

categories · object[]

Product categories the creator sells in: each entry is a parentCategoryId with optional childCategoryIds.

Minimum array length: 1

Show child attributes

contentPerformance · object

Lower bounds over the last 30 days. avgVideoViewsMin and avgShoppableVideoViewsMin can't be used together, and neither can avgLiveViewersMin and avgShoppableLiveViewersMin (the call returns 400).

Show child attributes

affiliate · object

Affiliate filters: avgCommissionRate bucket, postRate (fulfilment band), agencyStatus, fastGrowing, and notInvitedLast90Days.

Show child attributes

advanced · object

Per-region filters. Take option ids and sorter ids from GET /creators/discover/filters.

Show child attributes

dataGroups · enum<string>[]

Which data groups TikTok fills per row. All by default. When set, BASIC_CREATOR_INFORMATION is always added so every row keeps its open id.

Minimum array length: 1

Available options: BASIC_CREATOR_INFORMATION, CONTENT_PERFORMANCE, FOLLOWER_INFORMATION, COLLABORATION, SALES_AND_GMV

Response

200

application/json

One page of marketplace creators.

creators · object[] · required

Show child attributes

nextPageToken · string | null · required

Null on the last page.

searchKey · string | null · required

Pass back with the next page for stable results.

hasMore · boolean · required

quota · object | null · required

This shop's remaining Growi discovery budget after this call (TikTok doesn't expose its own counter). null when it can't be read.

Show child attributes

persisted · boolean · required

True only when persist was requested and the identity-spine write landed.