> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatordb.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Performance Information
> Retrieve advanced performance information of a specified TikTok creator, including post activity, follower growth, engagement metrics, and content performance.
Optionally pass `fields` in the request body to return only a subset of performance blocks. Requesting a subset bills fractionally, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). Per-field costs are not published yet. For how fractional costs work, see [Fractional Costs](/api-v3/fractional-calls).
## OpenAPI
````yaml /api-v3/api-v3.yaml post /tiktok/performance
openapi: 3.1.0
info:
version: 1.0.0
title: CreatorDB Headless API V3
description: '# CreatorDB Headless API V3'
contact:
name: CreatorDB
url: https://www.creatordb.app
email: support@creatordb.app
license:
url: http://www.apache.org/licenses/LICENSE-2.0.html
name: Apache 2.0
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
security:
- ApiKeyAuth: []
tags:
- name: Brand
description: Brand analysis endpoints including sponsor search and brand reports.
- name: Facebook
description: Facebook creator data endpoints with metrics and search capabilities.
- name: General Operations
description: >-
General-purpose endpoints such as API status, content retrieval, and
cross-platform operations.
- name: Instagram
description: >-
Instagram creator data endpoints with metrics and advanced search
capabilities.
- name: Niches
description: >-
Niche-related endpoints for content category analysis and related
searches.
- name: Threads
description: Threads creator data endpoints with basic metrics and historical data.
- name: TikTok
description: >-
TikTok creator data endpoints with metrics and advanced search
functionality.
- name: Topic
description: Topic-based analysis and reporting endpoints for content categorization.
- name: YouTube
description: >-
YouTube creator data endpoints including basic metrics, historical data,
and detailed analytics.
paths:
/tiktok/performance:
post:
tags:
- TikTok
summary: Get Performance Information
description: >-
Retrieve advanced performance information of a specified TikTok creator,
including post activity, follower growth, engagement metrics, and
content performance.
Optionally pass `fields` in the request
body to return only a subset of performance blocks. Requesting a subset
bills fractionally, capped at the full-bundle price. Fractional calls
must be enabled on your API key. Otherwise, a request that includes
`fields` returns a `400` error (`FractionalCallsNotEnabled`). Per-field
costs are not published yet. For how fractional costs work, see
[Fractional Costs](/api-v3/fractional-calls).
operationId: getTiktokPerformance
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- uniqueId
properties:
uniqueId:
type: string
description: >-
TikTok account ID. Accepts `tiktok` or `@tiktok` (@ is
stripped automatically).
pattern: ^@?[a-zA-Z0-9._-]+$
minLength: 1
maxLength: 101
examples:
- tiktok
fields:
type: array
description: >-
Subset of performance blocks to return. Omit or pass an
empty array to return the full response at the full-bundle
price. Per-field costs are not published yet.
items:
type: string
responses:
'200':
description: TikTok performance data returned successfully.
content:
application/json:
schema:
type: object
description: >-
Performance data of the specified TikTok creator returned
successfully.
properties:
data:
type: object
description: The performance metrics.
properties:
contentCountByDays:
type: object
description: >-
Published TikTok content over different time
intervals.
properties:
7d:
type: integer
description: Number of contents published in the past 7 days.
minimum: 0
examples:
- 4
30d:
type: integer
description: Number of contents published in the past 30 days.
minimum: 0
examples:
- 13
90d:
type: integer
description: Number of contents published in the past 90 days.
minimum: 0
examples:
- 45
required:
- 7d
- 30d
- 90d
ranking:
type: object
description: >-
Percentile rankings for various performance metrics,
benchmarked at the global, country, or language level.
A value of `1.0` indicates top 1%, while `0.5`
represents the median.
properties:
totalFollowers:
type: object
description: Percentile rank of the total follower count.
properties:
global:
type: number
description: >-
Percentile rank compared to all creators in
CreatorDB's database.
minimum: 0
maximum: 1
examples:
- 0.9912
country:
type: number
description: >-
Percentile rank among creators from the same
country.
minimum: 0
maximum: 1
examples:
- 0.9986
language:
type: number
description: >-
Percentile rank among creators using the same
primary language.
minimum: 0
maximum: 1
examples:
- 0.9764
required:
- global
- country
- language
avgViews:
type: object
description: Percentile rank of the average views per video.
properties:
global:
type: number
description: >-
Percentile rank compared to all creators in
CreatorDB's database.
minimum: 0
maximum: 1
examples:
- 0.9912
country:
type: number
description: >-
Percentile rank among creators from the same
country.
minimum: 0
maximum: 1
examples:
- 0.9986
language:
type: number
description: >-
Percentile rank among creators using the same
primary language.
minimum: 0
maximum: 1
examples:
- 0.9764
required:
- global
- country
- language
avgEngagementRate:
type: object
description: Percentile rank of the average engagement rate.
properties:
global:
type: number
description: >-
Percentile rank compared to all creators in
CreatorDB's database.
minimum: 0
maximum: 1
examples:
- 0.9912
country:
type: number
description: >-
Percentile rank among creators from the same
country.
minimum: 0
maximum: 1
examples:
- 0.9986
language:
type: number
description: >-
Percentile rank among creators using the same
primary language.
minimum: 0
maximum: 1
examples:
- 0.9764
required:
- global
- country
- language
required:
- totalFollowers
- avgViews
- avgEngagementRate
videosPerformanceRecent:
type: object
description: >-
Performance metrics of the creator's recent TikTok
videos.
properties:
likes:
type: object
properties:
all:
type: integer
description: Total number of likes.
minimum: 0
examples:
- 2944445
avg:
type: integer
description: >-
Average likes per video, rounded to an
integer.
minimum: 0
examples:
- 100
median:
type: integer
description: Median number of likes.
minimum: 0
examples:
- 48
min:
type: integer
description: Minimum number of likes.
minimum: 0
examples:
- 20
max:
type: integer
description: Maximum number of likes.
minimum: 0
examples:
- 149
required:
- all
- avg
- median
- min
- max
comments:
type: object
properties:
all:
type: integer
description: Total number of comments.
minimum: 0
examples:
- 222344
avg:
type: integer
description: >-
Average comments per video, rounded to an
integer.
minimum: 0
examples:
- 100
median:
type: integer
description: Median number of comments.
minimum: 0
examples:
- 48
min:
type: integer
description: Minimum number of comments.
minimum: 0
examples:
- 20
max:
type: integer
description: Maximum number of comments.
minimum: 0
examples:
- 149
required:
- all
- avg
- median
- min
- max
views:
type: object
properties:
all:
type: integer
description: Total number of views.
minimum: 0
examples:
- 3599
avg:
type: integer
description: >-
Average views per video, rounded to an
integer.
minimum: 0
examples:
- 100
median:
type: integer
description: Median number of views.
minimum: 0
examples:
- 48
min:
type: integer
description: Minimum number of views.
minimum: 0
examples:
- 20
max:
type: integer
description: Maximum number of views.
minimum: 0
examples:
- 149
required:
- all
- avg
- median
- min
- max
shares:
type: object
properties:
all:
type: integer
description: Total number of shares.
minimum: 0
examples:
- 3599
avg:
type: integer
description: >-
Average shares per video, rounded to an
integer.
minimum: 0
examples:
- 100
median:
type: integer
description: Median number of shares.
minimum: 0
examples:
- 48
min:
type: integer
description: Minimum number of shares.
minimum: 0
examples:
- 20
max:
type: integer
description: Maximum number of shares.
minimum: 0
examples:
- 149
required:
- all
- avg
- median
- min
- max
engagement:
type: object
description: >-
Engagement performance metrics including rates,
per-follower statistics and consistency analysis.
properties:
avgEngagementRate:
type: number
description: >-
Average engagement rate per video, rounded to
4th decimal place.
- *Engagement Rate = (Likes + Comments +
Shares)/ Followers*
minimum: 0
examples:
- 0.5201
likesPerFollower:
type: number
description: >-
Average likes per follower, rounded to 4th
decimal place.
minimum: 0
examples:
- 0.1111
commentsPerFollower:
type: number
description: >-
Average comments per follower, rounded to 4th
decimal place.
minimum: 0
examples:
- 0.1111
viewsPerFollower:
type: number
description: >-
Average views per follower, rounded to 4th
decimal place.
minimum: 0
examples:
- 0.1111
engagementConsistency:
type: object
description: Consistency of engagement performance.
properties:
cv:
type: number
description: >-
*cv = Standard Deviation of Engagement
Rate/ Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Lower values indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.1201
medianVsMean:
type: number
description: >-
*medianVsMean = Median Engagement
Rate/ Mean Engagement Rate*
- The value is rounded to 4th decimal
place
- Values closer to `1` indicate more
consistent performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.9001
topBottomRatio:
type: number
description: >-
*topBottomRatio = avg(Top 3
Engagement)/avg(Bottom 3 Engagement)*
- The value is rounded to 4th decimal
place.
- Lower ratios indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 1.2001
consistencyScore:
type:
- integer
- 'null'
description: >-
*consistencyScore = 100 -
[(cvScore\*weight_cv) +
(topBottomScore\*weight_topBottom) +
(medianVsMeanScore\*weight_medianVsMean)]*
- The score is rounded to an integer.
- A higher score indicates more stable and
consistent performance.
- If any of the three indicators is `0`,
the `consistencyScore` will be `null`.
minimum: 0
maximum: 100
examples:
- 63
consistencyLevel:
type: string
enum:
- high
- moderate
- low
- null
description: >-
A qualitative label based on the
`consistencyScore`:
- high: 81 - 100
- moderate: 51 - 80
- low: 0 - 50
- Returns `null` when the
`consistencyScore` is `null`.
examples:
- moderate
required:
- cv
- medianVsMean
- topBottomRatio
- consistencyScore
- consistencyLevel
required:
- avgEngagementRate
- likesPerFollower
- commentsPerFollower
- viewsPerFollower
- engagementConsistency
required:
- likes
- comments
- views
- shares
- engagement
recentVideosGrowth:
type: object
description: >-
Growth metrics for recent videos across 7, 30, and
90-day periods.
properties:
g7:
type: object
description: Growth metrics over 7 days.
properties:
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- engagementRate
g30:
type: object
description: Growth metrics over 30 days.
properties:
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- engagementRate
g90:
type: object
description: Growth metrics over 90 days.
properties:
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- engagementRate
required:
- g7
- g30
- g90
required:
- contentCountByDays
- ranking
- videosPerformanceRecent
- recentVideosGrowth
creditsUsed:
type: integer
description: Number of API credits consumed by this request.
examples:
- 1
creditsAvailable:
type: integer
description: Number of API credits remaining.
examples:
- -1
traceId:
type: string
description: Unique trace ID for each request.
examples:
- f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0
timestamp:
type: integer
description: >-
Time the response was generated, represented as a Unix
timestamp in milliseconds.
examples:
- 1750732453635
errorCode:
type: string
description: >-
Error code returned if the request fails. Empty if the
request is successful.
examples:
- ''
errorDescription:
type: string
description: >-
Description of the error. Empty if the request is
successful.
examples:
- ''
success:
type: boolean
description: '`true` if the request is successful.'
examples:
- true
required:
- data
- traceId
- timestamp
- errorCode
- errorDescription
- success
- creditsUsed
- creditsAvailable
examples:
default:
value:
data:
contentCountByDays:
7d: 2
30d: 12
90d: 38
followerGrowthIn30d: 0
ranking:
totalFollowers:
global: 0.0459
country: 0.0395
language: 0.0375
avgViews:
global: 0.9183
country: 0.9175
language: 0.9128
avgEngagementRate:
global: 0.219
country: 0.2332
language: 0.2263
videosPerformanceRecent:
likes:
all: 3253500
avg: 162675
median: 139950
min: 0
max: 0
comments:
all: 16780
avg: 839
median: 0
min: 0
max: 0
views:
all: 19514700
avg: 975735
median: 795300
min: 219000
max: 2700000
shares:
all: 150040
avg: 7502
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.1638
likesPerFollower: 0.0032
commentsPerFollower: 0
viewsPerFollower: 0.0193
engagementConsistency:
cv: 0.183
medianVsMean: 0.973
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
creditsUsed: 1
creditsAvailable: -1
traceId: 497b42dc5ed0208ddc6ab552053e90ec
timestamp: 1767938201026
errorCode: ''
errorDescription: ''
success: true
'400':
description: Validation error.
content:
application/json:
schema:
type: object
title: ValidationErrorResponse
properties:
success:
const: false
error:
type: string
message:
type: string
timestamp:
type: integer
required:
- success
- error
- message
- timestamp
examples:
missing uniqueId:
summary: Missing uniqueId
value:
success: false
error: VALIDATION_ERROR
message: 'Missing required field: ''uniqueId''.'
timestamp: 1770099403116
invalid uniqueId:
summary: Invalid uniqueId format
value:
success: false
error: VALIDATION_ERROR
message: >-
Invalid 'uniqueId' format. TikTok unique ID must be
between 1 to 101 characters.
timestamp: 1770099403116
'429':
description: Exceeded quota or rate limit.
content:
application/json:
schema:
type: object
title: QuotaErrorResponse
properties:
success:
const: false
error:
type: string
message:
type: string
remainingPlanCredit:
type: number
required:
- success
- error
- message
- remainingPlanCredit
examples:
rate limit:
summary: Rate limit exceeded
value:
success: false
error: RATE_LIMIT_EXCEEDED
message: Too many requests. Please try again later.
quota exceeded:
summary: Credit quota exceeded
value:
success: false
error: QUOTA_EXCEEDED
message: Not enough credits to complete this request.
security:
- ApiKeyAuth: []
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
x-codeSamples:
- lang: bash
label: cURL
source: |
curl -X POST "https://apiv3.creatordb.app/tiktok/performance" \
-H "Content-Type: application/json" \
-H "api-key: " \
-d '{ "uniqueId": "kallmekris" }'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
description: The valid CreatorDB API key for authentication.
name: api-key
in: header
````