> ## Documentation Index > Fetch the complete documentation index at: https://growi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml api-reference/tik-tok-shop-openapi.json POST /tik_tok_shop/creators/discover openapi: 3.0.3 info: title: 'Growi API: TikTok Shop' version: 1.0.0 description: >- Generated by scripts/gen_tik_tok_shop.rb from Growi's TikTok Shop route table. servers: - url: https://api.growi.io/api/public/v1 security: - bearerAuth: [] paths: /tik_tok_shop/creators/discover: post: summary: Discover creators description: >- 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. parameters: - name: organization_id in: query required: false schema: type: integer description: >- Use the TikTok Shop of this child brand (organization id) of your API key's organization requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: keyword: type: string maxLength: 100 description: >- Matches TikTok username and nickname only. Not a topic or semantic search. pageSize: type: integer enum: - 12 - 20 default: 20 description: TikTok accepts only 12 or 20. pageToken: type: string description: >- nextPageToken from the previous page. Omit on the first page. searchKey: type: string description: >- searchKey from the previous page. Pass it back so TikTok serves a stable result set across pages. followers: type: object additionalProperties: false properties: ageRanges: type: array minItems: 1 items: type: string enum: - AGE_RANGE_18_24 - AGE_RANGE_25_34 - AGE_RANGE_35_44 - AGE_RANGE_45_54 - AGE_RANGE_55_AND_ABOVE countMin: type: integer minimum: 0 countMax: type: integer minimum: 0 description: Must be >= countMin. gender: type: object additionalProperties: false required: - gender - minShareBp properties: gender: type: string enum: - MALE - FEMALE minShareBp: type: integer minimum: 0 maximum: 10000 description: >- Basis points: 6000 means at least 60% of followers are this gender. description: >- 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%). gmvRanges: type: array minItems: 1 items: type: string enum: - GMV_RANGE_0_100 - GMV_RANGE_100_1000 - GMV_RANGE_1000_10000 - GMV_RANGE_10000_AND_ABOVE description: >- TikTok's four fixed 30-day GMV buckets. Several buckets cover their union. unitsSoldRanges: type: array minItems: 1 items: type: string enum: - UNITS_SOLD_RANGE_0_10 - UNITS_SOLD_RANGE_10_100 - UNITS_SOLD_RANGE_100_1000 - UNITS_SOLD_RANGE_1000_AND_ABOVE description: TikTok's four fixed units-sold buckets. categories: type: array minItems: 1 items: type: object additionalProperties: false required: - parentCategoryId properties: parentCategoryId: type: string childCategoryIds: type: array minItems: 1 items: type: string description: One level below the parent only. description: >- Product categories the creator sells in: each entry is a parentCategoryId with optional childCategoryIds. contentPerformance: type: object additionalProperties: false description: >- 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). properties: avgVideoViewsMin: type: integer minimum: 0 maximum: 100000 avgShoppableVideoViewsMin: type: integer minimum: 0 maximum: 100000 avgEngagementRateMin: type: integer minimum: 0 maximum: 20 description: Whole percentage points. avgShoppableEngagementRateMin: type: integer minimum: 0 maximum: 20 description: Whole percentage points. avgLiveViewersMin: type: integer minimum: 0 maximum: 100000 avgShoppableLiveViewersMin: type: integer minimum: 0 maximum: 100000 affiliate: type: object additionalProperties: false properties: avgCommissionRate: type: string enum: - LESS_THAN_20% - LESS_THAN_15% - LESS_THAN_10% - LESS_THAN_5% postRate: type: string enum: - OK - GOOD - BETTER description: >- How often the creator posts after getting a sample. BETTER is the highest band. Omit for all. agencyStatus: type: string enum: - AGENCY_MANAGED - INDEPENDENT fastGrowing: type: boolean notInvitedLast90Days: type: boolean description: Only creators this shop has not invited in 90 days. description: >- Affiliate filters: avgCommissionRate bucket, postRate (fulfilment band), agencyStatus, fastGrowing, and notInvitedLast90Days. advanced: type: object additionalProperties: false description: >- Per-region filters. Take option ids and sorter ids from GET /creators/discover/filters. properties: contentPreference: type: array minItems: 1 items: type: string enum: - VIDEO - LIVE eligibleFlatFee: type: boolean description: US local sellers only. options: type: array minItems: 1 items: type: object additionalProperties: false required: - optionType - options properties: optionType: type: string enum: - OPTION_VERTICAL_PRO - OPTION_LANGUAGE - OPTION_CREATOR_LEVEL - OPTION_SORTER - OPTION_BRAND options: type: array minItems: 1 items: type: object additionalProperties: false required: - id properties: id: type: string name: type: string children: type: array minItems: 1 items: type: object additionalProperties: false required: - id properties: id: type: string name: type: string sorterAlgorithmId: type: string description: >- A sorters[].algorithmId from discover/filters. TikTok's default sort when omitted. dataGroups: type: array minItems: 1 items: type: string enum: - BASIC_CREATOR_INFORMATION - CONTENT_PERFORMANCE - FOLLOWER_INFORMATION - COLLABORATION - SALES_AND_GMV description: >- 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. example: 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' responses: '200': description: One page of marketplace creators. content: application/json: schema: type: object required: - creators - nextPageToken - searchKey - hasMore - quota - persisted properties: creators: type: array items: type: object required: - openId properties: openId: type: string description: >- TikTok creator open id. Use it for target-collab invites and DMs. username: type: string nullable: true nickname: type: string nullable: true avatarUrl: type: string nullable: true selectionRegion: type: string nullable: true categoryIds: type: array items: type: string followerCount: type: integer nullable: true avgShoppableVideoViews: type: integer nullable: true description: TikTok avg_ec_video_view_count, last 30 days. avgShoppableLiveViewers: type: integer nullable: true description: TikTok avg_ec_live_uv, last 30 days. gmv: type: object nullable: true properties: amount: type: string nullable: true currency: type: string nullable: true description: Precise GMV, only when the creator shares it. videoGmv: type: object nullable: true properties: amount: type: string nullable: true currency: type: string nullable: true liveGmv: type: object nullable: true properties: amount: type: string nullable: true currency: type: string nullable: true gmvRange: type: object nullable: true description: >- Set instead of gmv when the creator does not share precise data. properties: min: type: string nullable: true max: type: string nullable: true formatted: type: string nullable: true currency: type: string nullable: true unitsSoldRange: type: object nullable: true properties: min: type: integer nullable: true max: type: integer nullable: true formatted: type: string nullable: true topFollowerDemographics: type: object nullable: true properties: ageRanges: type: array items: type: string majorGender: type: object nullable: true properties: gender: type: string nullable: true percentageBp: type: integer nullable: true description: 'Basis points: 6524 = 65.24%.' profile: type: object nullable: true description: >- Null when TikTok returns an empty profile (not supported for this account or region). properties: ppsScore: type: string nullable: true creatorLevel: type: integer nullable: true isFastGrowing: type: boolean nullable: true isRisingStar: type: boolean nullable: true isOfficialRecommend: type: boolean nullable: true hasCollaborated: type: boolean nullable: true hasInvitedLast90Days: type: boolean nullable: true isBlockedByShop: type: boolean nullable: true isEligibleFlatFee: type: boolean nullable: true mcnName: type: string nullable: true userTypeTags: type: array items: type: integer nextPageToken: type: string nullable: true description: Null on the last page. searchKey: type: string nullable: true description: Pass back with the next page for stable results. hasMore: type: boolean quota: type: object nullable: true description: >- This shop's remaining Growi discovery budget after this call (TikTok doesn't expose its own counter). null when it can't be read. properties: scope: type: string enum: - gateway_discover_daily limit: type: integer used: type: integer remaining: type: integer resetsAt: type: string format: date-time persisted: type: boolean description: >- True only when persist was requested and the identity-spine write landed. example: 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 '400': description: >- invalid_request: unknown key, bad enum or range, pageSize not 12/20, or a mutually exclusive pair; also a body that is not a valid JSON object content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '403': description: >- The shop's TikTok authorization doesn't include this data (`code: scope_not_granted`), so the seller has to re-authorize the shop. Read-only (viewer) API keys can't call POST endpoints content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '404': description: >- `organization_id` isn't an active child brand of your organization, or the record you asked for doesn't exist content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '422': description: >- No TikTok Shop is connected for this organization. A parent organization whose shops sit on its child brands has to pass `organization_id`. Also returned when the shop isn't connected through TikTok's official API (`code: unsupported_on_web_only_shop`) content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '429': description: >- Rate limited: one call every 2 seconds and an hourly cap per API key. See `Retry-After` and the `X-RateLimit-*` headers. Also returned when TikTok's daily quota for this shop is spent (`code: quota_exhausted`) content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '502': description: >- TikTok refused or failed. `error` is a fixed message and `code` names the failure when there is one content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' components: schemas: TikTokShopError: type: object required: - error properties: error: type: string description: What went wrong code: type: string description: Machine-readable reason, when there is one securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.