> ## 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 History
> Retrieve daily performance snapshots for a specified TikTok creator within a specific period, including upload activity, follower growth, engagement metrics, and video performance. Dates are returned as Unix timestamps in milliseconds.
## OpenAPI
````yaml /api-v3/api-v3.yaml get /tiktok/performance-history
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-history:
get:
tags:
- TikTok
summary: Get Performance History
description: >-
Retrieve daily performance snapshots for a specified TikTok creator
within a specific period, including upload activity, follower growth,
engagement metrics, and video performance. Dates are returned as Unix
timestamps in milliseconds.
operationId: getTiktokPerformanceHistory
parameters:
- name: uniqueId
in: query
description: >-
TikTok account ID. Accepts `tiktok` or `@tiktok` (@ is stripped
automatically).
required: true
schema:
type: string
pattern: ^@?[a-zA-Z0-9._-]+$
minLength: 1
maxLength: 101
examples:
- tiktok
- name: pastDayRange
in: query
description: >-
Returns one data point per day over the requested range. For
example, `30` returns the past 30 days of daily snapshots. Valid
range: `1`-`365`.
required: true
schema:
type: string
pattern: ^[1-9]\d*$
examples:
- '30'
responses:
'200':
description: TikTok performance historical data returned successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: >-
The historical performance metrics of the specified TikTok
account.
properties:
histories:
type: array
description: >-
Historical performance snapshots, each containing
metrics, and a corresponding Unix timestamp in
milliseconds.
items:
type: object
description: >-
A snapshot of the performance metrics on the
specified date.
properties:
timestamp:
type: integer
description: >-
The performance snapshot date, represented as a
Unix timestamp in milliseconds.
exclusiveMinimum: 0
examples:
- 1755273600000
totalFollowers:
type: integer
description: Total number of followers.
minimum: 0
examples:
- 38100
totalFollowing:
type: integer
description: Total number of accounts followed.
minimum: 0
examples:
- 4757
totalContents:
type: integer
description: Total number of videos.
minimum: 0
examples:
- 305
videosPerformanceRecent:
type: object
description: >-
Performance metrics of the most 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 `consistencyScore`
is `null`.
examples:
- moderate
required:
- cv
- medianVsMean
- topBottomRatio
- consistencyScore
- consistencyLevel
required:
- avgEngagementRate
- likesPerFollower
- commentsPerFollower
- viewsPerFollower
- engagementConsistency
required:
- likes
- comments
- views
- shares
- engagement
required:
- timestamp
- totalFollowers
- totalFollowing
- totalContents
- videosPerformanceRecent
required:
- histories
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:
histories:
- timestamp: 1767852641724
totalFollowers: 155900000
totalFollowing: 1289
totalContents: 2893
videosPerformanceRecent:
likes:
all: 11215700
avg: 560785
median: 226700
min: 0
max: 0
comments:
all: 49820
avg: 2491
median: 0
min: 0
max: 0
views:
all: 202000000
avg: 10100000
median: 7750000
min: 5000000
max: 27800000
shares:
all: 121440
avg: 6072
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0442
likesPerFollower: 0.0036
commentsPerFollower: 0
viewsPerFollower: 0.0648
engagementConsistency:
cv: 0.7354
medianVsMean: 0.748
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1767766241724
totalFollowers: 156000000
totalFollowing: 1287
totalContents: 2892
videosPerformanceRecent:
likes:
all: 11204200
avg: 560210
median: 226500
min: 0
max: 0
comments:
all: 49660
avg: 2483
median: 0
min: 0
max: 0
views:
all: 201200000
avg: 10060000
median: 7650000
min: 5000000
max: 27700000
shares:
all: 121260
avg: 6063
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0442
likesPerFollower: 0.0036
commentsPerFollower: 0
viewsPerFollower: 0.0645
engagementConsistency:
cv: 0.7352
medianVsMean: 0.7495
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1767679841724
totalFollowers: 156000000
totalFollowing: 1287
totalContents: 2892
videosPerformanceRecent:
likes:
all: 11984300
avg: 599215
median: 235450
min: 0
max: 0
comments:
all: 50980
avg: 2549
median: 0
min: 0
max: 0
views:
all: 203500000
avg: 10175000
median: 7600000
min: 4900000
max: 27500000
shares:
all: 105240
avg: 5262
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0474
likesPerFollower: 0.0038
commentsPerFollower: 0
viewsPerFollower: 0.0652
engagementConsistency:
cv: 0.6964
medianVsMean: 0.7637
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1767593441724
totalFollowers: 156000000
totalFollowing: 1285
totalContents: 2892
videosPerformanceRecent:
likes:
all: 11064300
avg: 553215
median: 225950
min: 0
max: 0
comments:
all: 49040
avg: 2452
median: 0
min: 0
max: 0
views:
all: 197500000
avg: 9875000
median: 7550000
min: 4900000
max: 27300000
shares:
all: 120280
avg: 6014
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0443
likesPerFollower: 0.0035
commentsPerFollower: 0
viewsPerFollower: 0.0633
engagementConsistency:
cv: 0.7317
medianVsMean: 0.752
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1767507041724
totalFollowers: 155900000
totalFollowing: 1290
totalContents: 2892
videosPerformanceRecent:
likes:
all: 11040000
avg: 552000
median: 225250
min: 0
max: 0
comments:
all: 48640
avg: 2432
median: 0
min: 0
max: 0
views:
all: 195200000
avg: 9760000
median: 7500000
min: 4800000
max: 27100000
shares:
all: 119460
avg: 5973
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0445
likesPerFollower: 0.0035
commentsPerFollower: 0
viewsPerFollower: 0.0626
engagementConsistency:
cv: 0.7338
medianVsMean: 0.7553
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1767334241724
totalFollowers: 156000000
totalFollowing: 1290
totalContents: 2892
videosPerformanceRecent:
likes:
all: 11014300
avg: 550715
median: 224100
min: 0
max: 0
comments:
all: 48120
avg: 2406
median: 0
min: 0
max: 0
views:
all: 193100000
avg: 9655000
median: 7450000
min: 4800000
max: 26900000
shares:
all: 118800
avg: 5940
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0447
likesPerFollower: 0.0035
commentsPerFollower: 0
viewsPerFollower: 0.0619
engagementConsistency:
cv: 0.7335
medianVsMean: 0.7513
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1767161441724
totalFollowers: 156000000
totalFollowing: 1290
totalContents: 2892
videosPerformanceRecent:
likes:
all: 10885000
avg: 544250
median: 222650
min: 0
max: 0
comments:
all: 47520
avg: 2376
median: 0
min: 0
max: 0
views:
all: 190700000
avg: 9535000
median: 7400000
min: 4700000
max: 26700000
shares:
all: 117860
avg: 5893
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0448
likesPerFollower: 0.0035
commentsPerFollower: 0
viewsPerFollower: 0.0611
engagementConsistency:
cv: 0.7311
medianVsMean: 0.7571
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1767075041724
totalFollowers: 156000000
totalFollowing: 1290
totalContents: 2892
videosPerformanceRecent:
likes:
all: 11769800
avg: 588490
median: 231050
min: 0
max: 0
comments:
all: 48800
avg: 2440
median: 0
min: 0
max: 0
views:
all: 193300000
avg: 9665000
median: 7350000
min: 4700000
max: 26500000
shares:
all: 101960
avg: 5098
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0482
likesPerFollower: 0.0038
commentsPerFollower: 0
viewsPerFollower: 0.062
engagementConsistency:
cv: 0.6949
medianVsMean: 0.7591
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1766988641724
totalFollowers: 156000000
totalFollowing: 1290
totalContents: 2891
videosPerformanceRecent:
likes:
all: 11638900
avg: 581945
median: 229400
min: 0
max: 0
comments:
all: 48240
avg: 2412
median: 0
min: 0
max: 0
views:
all: 190500000
avg: 9525000
median: 7250000
min: 4600000
max: 26200000
shares:
all: 100900
avg: 5045
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0482
likesPerFollower: 0.0037
commentsPerFollower: 0
viewsPerFollower: 0.0611
engagementConsistency:
cv: 0.6905
medianVsMean: 0.7632
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1766729441724
totalFollowers: 156000000
totalFollowing: 1290
totalContents: 2891
videosPerformanceRecent:
likes:
all: 11487300
avg: 574365
median: 220450
min: 0
max: 0
comments:
all: 47220
avg: 2361
median: 0
min: 0
max: 0
views:
all: 185600000
avg: 9280000
median: 7100000
min: 4500000
max: 25300000
shares:
all: 98820
avg: 4941
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0487
likesPerFollower: 0.0037
commentsPerFollower: 0
viewsPerFollower: 0.0595
engagementConsistency:
cv: 0.6899
medianVsMean: 0.7584
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
- timestamp: 1766383841724
totalFollowers: 156000000
totalFollowing: 1290
totalContents: 2891
videosPerformanceRecent:
likes:
all: 11317300
avg: 565865
median: 214300
min: 0
max: 0
comments:
all: 45960
avg: 2298
median: 0
min: 0
max: 0
views:
all: 179000000
avg: 8950000
median: 6800000
min: 4400000
max: 23600000
shares:
all: 95080
avg: 4754
median: 0
min: 0
max: 0
engagement:
avgEngagementRate: 0.0493
likesPerFollower: 0.0036
commentsPerFollower: 0
viewsPerFollower: 0.0574
engagementConsistency:
cv: 0.6945
medianVsMean: 0.7539
topBottomRatio: 0
consistencyScore: null
consistencyLevel: null
creditsUsed: 1
creditsAvailable: -1
traceId: 20fb4d4399fcf96d227bd016d6171858
timestamp: 1767939041800
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 pastDayRange:
summary: pastDayRange out of bounds
value:
success: false
error: VALIDATION_ERROR
message: '''pastDayRange'' out of range. Must be between 1 and 365.'
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 GET
"https://apiv3.creatordb.app/tiktok/performance-history?uniqueId=charlidamelio&pastDayRange=30"
\
-H "Content-Type: application/json" \
-H "api-key: "
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
description: The valid CreatorDB API key for authentication.
name: api-key
in: header
````