> ## 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 TikTok historical data > Get the basic metrics and historical data of a creator's TikTok account. ## OpenAPI ````yaml /api-v2/api-v2.yaml get /tiktokHistory openapi: 3.1.0 info: version: '2' title: CreatorDB Headless APIService description: >- Generated from swaggerComponentIndex.json by core-types-json-schema (https://github.com/grantila/core-types-json-schema). Use OpenAPI 3.1.0 version with direct JSON Schema support termsOfService: https://www.creatordb.app 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 x-id: indexForSwagger.yaml servers: - url: https://dev.creatordb.app/v2 description: CreatorDB API Endpoint - prod version security: [] tags: - name: General Operations description: >- General-purpose endpoints such as API status, content retrieval, and cross-platform operations - name: YouTube description: >- YouTube creator data endpoints including basic metrics, historical data, and detailed analytics - name: Instagram description: >- Instagram creator data endpoints with metrics and advanced search capabilities - name: TikTok description: >- TikTok creator data endpoints with metrics and advanced search functionality - name: Threads description: Threads creator data endpoints with basic metrics and historical data - name: Facebook description: Facebook creator data endpoints with metrics and search capabilities - name: Topic description: Topic-based analysis and reporting endpoints for content categorization - name: Brand description: Brand analysis endpoints including sponsor search and brand reports - name: Niches description: Niche-related endpoints for content category analysis and related searches paths: /tiktokHistory: get: tags: - TikTok summary: Get TikTok historical data description: Get the basic metrics and historical data of a creator's TikTok account. operationId: getTiktokHistory parameters: - name: apiId in: header description: '' required: true schema: type: string examples: - LE6DPZQkR3TQShxofXoD2j8qCBu1-f0jti665m1t50dwDD12W - name: tiktokId in: query description: '' required: true schema: type: string examples: - .....aaaaesthetic responses: '200': description: OK content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BasicTikTokAndHistoryResult' quotaUsed: type: number description: API credits that were used to make this call. quotaUsedTotal: type: number description: Total API credits used since the last billing cycle. remainingPlanCredit: type: number description: >- The number of remaining free API credits that come with your subscription plan. These API credits are renewed every billing cycle. remainingPrepurchasedCredit: type: number description: >- The number of remaining extra purchased API credits. These API credits do not expire until used. timestamp: type: number description: >- Unix timestamp of the call request that the server received. error: type: string description: Errors that occurred during the API call. success: type: boolean description: It is TRUE when the call is successful. examples: default: value: data: basicTikTok: tiktokId: .....aaaaesthetic tiktokName: .....aaesthetic youtubeId: '' instagramId: '' avatar: >- https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/9ab6fe2ee7db151807c30ba7f59668da~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=b8c906e2&x-expires=1755054000&x-signature=6DfhDAeymRGgB5CgmhS5RJTrRZc%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=my description: |- pr/collab email: aaaaesthetic.uk@gmail.com pinterest: xaaesthetic relatedUsers: - bts_official_bighit - twice_tiktok_official - joeman0828 recentVideos: - uploadDate: 1750206628000 videoId: '7517080182545517846' length: 12 cover: >- https://p16-pu-sign-no.tiktokcdn-eu.com/tos-no1a-p-0037-no/oIZEoBgFyvAEPCIaISITGBBaiioFhYAAKEhSW~tplv-tiktokx-origin.image?dr=14575&x-expires=1755054000&x-signature=WJK3EPtAvMJLkxPQ5On9NXvGczc%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my audioId: '7517080135716080406' audioTitle: original sound audioAuthor: .....aaesthetic audioAlbum: '' hearts: 28 shares: 0 comments: 0 plays: 235 engageRate: 0.11914893617021277 hashtags: - '#lilies' - '#lillies' - '#flowers' commerceHashtags: [] isAd: false isDuetEnabled: true - uploadDate: 1704584094000 videoId: '7321132893059796257' length: 0 cover: >- https://p16-sign-va.tiktokcdn.com/tos-maliva-i-photomode-us/60d4b9d3150340028a6e0f58b422729f~tplv-photomode-image.jpeg?dr=14555&x-expires=1755054000&x-signature=H3ud%2Fo7iUhhA4spcY%2Bm8J88%2Fkic%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=9b759fb9&idc=my&ftpl=1 audioId: '7289498627536374571' audioTitle: my love mine all mine audioAuthor: ‍r7ptor audioAlbum: '' hearts: 157 shares: 0 comments: 13 plays: 1813 engageRate: 0.09376723662437948 hashtags: [] commerceHashtags: [] isAd: false isDuetEnabled: false - uploadDate: 1703942994000 videoId: '7318379374288424225' length: 11 cover: >- https://p16-common-sign-useastred.tiktokcdn-eu.com/tos-useast2a-p-0037-euttp/o4DxIE4DJQNIfFiI8eAfM8BqfKG4Ejg3gLIDAG~tplv-tiktokx-origin.image?dr=14575&x-expires=1755054000&x-signature=2foUcmASK3sJvJ3wopHhA3WWcdg%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my audioId: '7242418278340119323' audioTitle: What's Luv? (feat. Ja-Rule & Ashanti) audioAuthor: Fat Joe audioAlbum: Jealous Ones Still Envy (J.O.S.E) hearts: 238 shares: 1 comments: 7 plays: 1918 engageRate: 0.12825860271115747 hashtags: - '#xmas' - '#christmas' - '#xmas2023' commerceHashtags: [] isAd: false isDuetEnabled: false isVerified: false isPrivateAccount: false hashtags: - '#foryoupage' - '#fyp' - '#beads' commerceHashtags: [] country: GBR lang: eng followers: 38100 following: 4757 hearts: 711300 videos: 305 avgLength: 13 avgHearts: 3167 avgShares: 13 avgComments: 16 avgPlays: 22941 engageRate: 0.11153172478142909 gRateFollowers: -0.002379819133745835 gRateHearts: 0.00012782493097453728 gRateAvgHearts: 0 gRateAvgShares: 0 gRateAvgComments: 0 gRateAvgPlays: 0.0002378262679112908 gRateEngageRate: -0.0021331956549717913 histories: - timestamp: 1754841600000 followers: 38100 following: 4757 hearts: 711300 videos: 305 avgLength: 13 avgHearts: 3167 avgShares: 13 avgComments: 16 avgPlays: 22941 engageRate: 0.13934786424775364 - timestamp: 1754150400000 followers: 38100 following: 4757 hearts: 711300 videos: 305 avgLength: 13 avgHearts: 3167 avgShares: 13 avgComments: 16 avgPlays: 22941 engageRate: 0.1393493417781768 - timestamp: 1753545600000 followers: 38100 following: 4757 hearts: 711200 videos: 305 avgLength: 13 avgHearts: 3167 avgShares: 13 avgComments: 16 avgPlays: 22938 engageRate: 0.13936097011513754 quotaUsed: 3 quotaUsedTotal: 6027 remainingPlanCredit: 993973 remainingPrepurchasedCredit: 0 timestamp: 1755503515911 error: '' success: true '403': description: Forbidden content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BasicTikTokAndHistoryResult' quotaUsed: type: number description: API credits that were used to make this call. quotaUsedTotal: type: number description: Total API credits used since the last billing cycle. remainingPlanCredit: type: number description: >- The number of remaining free API credits that come with your subscription plan. These API credits are renewed every billing cycle. remainingPrepurchasedCredit: type: number description: >- The number of remaining extra purchased API credits. These API credits do not expire until used. timestamp: type: number description: >- Unix timestamp of the call request that the server received. error: type: string description: Errors that occurred during the API call. success: type: boolean description: It is TRUE when the call is successful. examples: default: value: data: null quotaUsed: 0 quotaUsedTotal: 0 remainingPlanCredit: 0 remainingPrepurchasedCredit: 0 timestamp: 1755503514760 error: TikTokIdNotFound success: false servers: - url: https://dev.creatordb.app/v2 description: CreatorDB API Endpoint - prod version x-codeSamples: - lang: bash label: cURL source: | curl --request GET \ --url 'https://dev.creatordb.app/v2/tiktokHistory?tiktokId=.....aaaaesthetic' \ --header 'Accept: application/json' \ --header 'apiId: LE6DPZQkR3TQShxofXoD2j8qCBu1-f0jti665m1t50dwDD12W' components: schemas: BasicTikTokAndHistoryResult: type: object additionalProperties: false properties: basicTikTok: $ref: '#/components/schemas/BasicTikTok' description: BasicTikTokAndHistoryResult.basicTikTok histories: type: array items: $ref: '#/components/schemas/TikTokHistoryDay' required: - basicTikTok - histories BasicTikTok: type: object additionalProperties: false properties: tiktokId: type: string description: A creator's TikTok handle that is recognizable in the URL. tiktokName: type: string description: This creator's editable TikTok display name. youtubeId: type: string description: >- The TikTok creator's YouTube channel ID is displayed if they have one. instagramId: type: string description: >- Instagram ID of this TikTok creator if they have one. Otherwise, this field will be blank. avatar: type: string description: URL of the TikTok creator's profile picture. description: type: string description: >- The creator's biography displayed on the TikTok creator's profile page. relatedUsers: type: array description: TikTok recommended accounts that are similar to this TikTok creator. items: type: string recentVideos: type: array items: $ref: '#/components/schemas/TikTokVideoInfo' isVerified: type: boolean description: >- It is TRUE when this TikTok creator's account has a verification badge. isPrivateAccount: type: boolean description: It is TRUE when this TikTok creator's account is private. hashtags: type: array description: Total unique hashtags used in this creator's last 30 TikTok posts. items: type: string commerceHashtags: type: array description: Raw hashtag data from TikTok. items: type: string country: type: string description: The TikTok creator's country of origin. lang: type: string description: The language used in the TikTok creator's content. followers: type: number description: The total followers of this creator's TikTok account. following: type: number description: Other TikTok accounts that this TikTok creator is following. hearts: type: number description: Total number of hearts this creator received for all TikTok posts. videos: type: number description: Total videos uploaded by the TikTok creator. avgLength: type: number description: Average posted TikTok video length in seconds. avgHearts: type: number description: Average hearts per TikTok post. avgShares: type: number description: Average TikTok post shares. avgComments: type: number description: Average comments per TikTok post. avgPlays: type: number description: Average plays of the TikTok post. engageRate: type: number description: >- Average TikTok engagement rate for the last 30 posts. The engagement rate is calculated by adding hearts, comments, and shares and then dividing by the total plays. gRateFollowers: type: number description: >- The growth rate of followers for this creator's TikTok account over the last 30 days. gRateHearts: type: number description: >- The growth rate of hearts for this creator's TikTok account over the last 30 days. gRateAvgHearts: type: number description: The growth rate of average hearts per TikTok post over 30 days. gRateAvgShares: type: number description: >- The growth rate of the average shares per TikTok post over the last 30 days. gRateAvgComments: type: number description: >- The growth rate of the average comments per TikTok post over the last 30 days. gRateAvgPlays: type: number description: >- The growth rate of the average plays per TikTok post over the last 30 days. gRateEngageRate: type: number description: >- The growth rate of the average engagement rate per TikTok post over the last 30 days. The engagement rate is calculated by adding hearts, comments, and shares, and then dividing by the total plays. required: - tiktokId - tiktokName - youtubeId - instagramId - avatar - description - relatedUsers - recentVideos - isVerified - isPrivateAccount - hashtags - commerceHashtags - country - lang - followers - following - hearts - videos - avgLength - avgHearts - avgShares - avgComments - avgPlays - engageRate - gRateFollowers - gRateHearts - gRateAvgHearts - gRateAvgShares - gRateAvgComments - gRateAvgPlays - gRateEngageRate TikTokHistoryDay: type: object additionalProperties: false properties: timestamp: type: number description: Unix timestamp when the TikTok data snapshot was collected. followers: type: number description: Total followers this TikTok creator has. following: type: number description: Other TikTok pages that this TikTok creator is following. hearts: type: number description: >- The total number of hearts the TikTok creator received for all posts. videos: type: number description: Total uploads this TikTok creator has. avgLength: type: number description: The average length of recent TikTok video posts in seconds. avgHearts: type: number description: Average hearts per TikTok post for a specific date. avgShares: type: number description: The average shares per TikTok post. avgComments: type: number description: The average comments per TikTok post. avgPlays: type: number description: The average plays of the TikTok post. engageRate: type: number description: >- The average TikTok engagement rate for the last 30 posts. The engagement rate is calculated by adding hearts, comments, and shares and dividing by the total plays. required: - timestamp - followers - following - hearts - videos - avgLength - avgHearts - avgShares - avgComments - avgPlays - engageRate TikTokVideoInfo: type: object additionalProperties: false properties: uploadDate: type: number description: Unix timestamp of the TikTok post upload time. videoId: type: string description: Unique generated ID of the TikTok post. length: type: number description: The length of the TikTok video in seconds. cover: type: string description: URL of the thumbnail image of a TikTok post. audioId: type: string description: Unique ID of the TikTok audio file. audioTitle: type: string description: Given display name of the TikTok audio file. audioAuthor: type: string description: Audio author raw data from TikTok. audioAlbum: type: string description: Album raw data from TikTok. Otherwise, this will be a blank field. hearts: type: number description: The number of hearts received by the TikTok post. shares: type: number description: The number of shares of the TikTok post. comments: type: number description: The number of comments on the TikTok post. plays: type: number description: The number of plays of the TikTok post. engageRate: type: number description: Engagement rate of the TikTok video. hashtags: type: array description: Hashtags that are used in the TikTok video caption. items: type: string commerceHashtags: type: array description: Hashtags related to a TikTok promotional campaign. items: type: string isAd: type: boolean description: It is TRUE when the TikTok video is an advertisement. isDuetEnabled: type: boolean description: >- It is TRUE when the TikTok creator has enabled duet feature for this post. required: - uploadDate - videoId - length - cover - audioId - audioTitle - audioAuthor - audioAlbum - hearts - shares - comments - plays - engageRate - hashtags - commerceHashtags - isAd - isDuetEnabled ````