Tik Tok

List TikTok library items

Returns TikTok ads and organic videos from the Public API TikTok library. This namespace is separate from the Meta-only /v1/ads endpoints and is backed by the tiktoks-search Elasticsearch alias.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

search?string

Lengthlength <= 500

searchArea?string

Default"all"

Value in"all" | "caption" | "profile" | "hashtag" | "music"

type?string

Default"all"

Value in"all" | "ad" | "organic"

status?string

Default"all"

Value in"all" | "active" | "inactive"

mediaTypes?array<>

Itemsitems <= 20

languages?array<>

ISO 639-1 codes (en, fr) or English language names (English, french), case-insensitive.

Itemsitems <= 20

countries?array<>

Itemsitems <= 20

hashtags?array<>

Hashtags with or without #, case-insensitive.

Itemsitems <= 20

tiktokPageId?string

Lengthlength <= 255

domain?string

Lengthlength <= 253

handle?string

Lengthlength <= 64

publishedAfter?string

Formatdate-time

publishedBefore?string

Formatdate-time

minViews?integer

Range0 <= value

maxViews?integer

Range0 <= value

minEngagementRate?number

Range0 <= value

maxEngagementRate?number

Range0 <= value <= 100

sortBy?string

Default"newest"

Value in

"relevance" | "newest" | "updatedAt" | "views" | "likes" | "comments" | "shares" | "saves" | "engagementRate" | "daysRunning" | "followers"

order?string

Default"desc"

Value in"asc" | "desc"

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 50

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/tiktok/library"

{  "requestId": "req_123",  "data": [    {      "id": "tiktok_7078586231734521093",      "tiktokId": "string",      "type": "ad",      "status": "active",      "isPinned": true,      "publishedAt": "string",      "createdAt": "string",      "updatedAt": "string",      "daysRunning": 0,      "media": {        "type": "video",        "thumbnailUrl": "string",        "mediaUrl": "string",        "videoUrl": "string",        "imageUrls": [          "string"        ],        "medias": [          {            "type": "video",            "url": "string",            "order": 0          }        ],        "durationSec": 0,        "mediaCount": 0,        "imageCount": 0      },      "content": {        "description": "string",        "language": "string",        "category": "string",        "hashtags": [          "string"        ],        "music": {          "id": "string",          "title": "string",          "author": "string"        }      },      "metrics": {        "views": 0,        "likes": 0,        "comments": 0,        "saves": 0,        "shares": 0,        "reposts": 0,        "engagementRate": 0,        "rank": 0,        "rankPercent": 0,        "relevanceScore": 0,        "deltaRank3d": 0,        "deltaRank7d": 0,        "deltaRank14d": 0,        "deltaRank30d": 0      },      "profile": {        "id": "string",        "handle": "string",        "name": "string",        "avatarUrl": "string",        "bio": "string",        "bioUrl": "string",        "accountType": "string",        "secUid": "string",        "followers": 0,        "following": 0,        "totalTikToks": 0,        "newTikToks": 0,        "percentAds": 0,        "views": 0,        "likes": 0,        "pageCreation": "string"      },      "shop": {        "id": "string",        "domain": "string",        "name": "string",        "logoUrl": "string",        "faviconUrl": "string",        "countryCode": "string",        "monthlyVisits": 0,        "trafficGrowth30d": 0,        "productsCount": 0,        "googleCategoryIds": [          0        ]      },      "pin": {        "isCurrent": true,        "firstPinnedAt": "string",        "lastPinnedAt": "string",        "lastUnpinnedAt": "string"      },      "pageSnapshot": {        "recordedAt": "string",        "adsCount": 0,        "organicCount": 0,        "totalTikToks": 0,        "dailyViews": 0,        "dailyLikes": 0,        "dailyFollowers": 0      },      "indexedAt": "string"    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 250,    "totalPages": 10  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Query TikTok library items

Advanced TikTok library query over ES-backed fields only. It intentionally does not use the internal Next /api/tiktok-ads route or per-request Postgres hydration.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

search?array<string>

keywordMode?string

Default"any"

Value in"any" | "all"

searchArea?string

Default"all"

Value in"all" | "caption" | "profile" | "hashtag" | "music"

type?string

Default"all"

Value in"all" | "ad" | "organic"

status?string

Default"all"

Value in"all" | "active" | "inactive"

mediaTypes?array<>

languages?array<string>

ISO 639-1 codes (en, fr) or English language names (English, french), case-insensitive.

countries?array<string>

categories?array<string>

TikTok content categories, case-insensitive.

hashtags?array<string>

tiktokPageIds?array<string>

tiktokPageId?string

websiteId?string

domain?string

handle?string

hasShopLinked?string

Value in"yes" | "no"

publishedAfter?string

publishedBefore?string

updatedAfter?string

updatedBefore?string

minDaysRunning?number

maxDaysRunning?number

minViews?number

maxViews?number

minLikes?number

minShares?number

minEngagementRate?number

maxEngagementRate?number

minFollowers?number

minProfileViews?number

isPinned?boolean

sortBy?string

Default"newest"

Value in

"relevance" | "newest" | "updatedAt" | "views" | "likes" | "comments" | "shares" | "saves" | "engagementRate" | "daysRunning" | "followers"

order?string

Default"desc"

Value in"asc" | "desc"

page?object

Default1

Range1 <= value

limit?object

Default25

Range1 <= value <= 50

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/tiktok/library/query" \  -H "Content-Type: application/json" \  -d '{    "search": [      "protein gummies"    ],    "searchArea": "caption",    "type": "ad",    "status": "active",    "minViews": 10000,    "sortBy": "views",    "order": "desc",    "limit": 10  }'

{  "requestId": "req_123",  "data": [    {      "id": "tiktok_7078586231734521093",      "tiktokId": "string",      "type": "ad",      "status": "active",      "isPinned": true,      "publishedAt": "string",      "createdAt": "string",      "updatedAt": "string",      "daysRunning": 0,      "media": {        "type": "video",        "thumbnailUrl": "string",        "mediaUrl": "string",        "videoUrl": "string",        "imageUrls": [          "string"        ],        "medias": [          {            "type": "video",            "url": "string",            "order": 0          }        ],        "durationSec": 0,        "mediaCount": 0,        "imageCount": 0      },      "content": {        "description": "string",        "language": "string",        "category": "string",        "hashtags": [          "string"        ],        "music": {          "id": "string",          "title": "string",          "author": "string"        }      },      "metrics": {        "views": 0,        "likes": 0,        "comments": 0,        "saves": 0,        "shares": 0,        "reposts": 0,        "engagementRate": 0,        "rank": 0,        "rankPercent": 0,        "relevanceScore": 0,        "deltaRank3d": 0,        "deltaRank7d": 0,        "deltaRank14d": 0,        "deltaRank30d": 0      },      "profile": {        "id": "string",        "handle": "string",        "name": "string",        "avatarUrl": "string",        "bio": "string",        "bioUrl": "string",        "accountType": "string",        "secUid": "string",        "followers": 0,        "following": 0,        "totalTikToks": 0,        "newTikToks": 0,        "percentAds": 0,        "views": 0,        "likes": 0,        "pageCreation": "string"      },      "shop": {        "id": "string",        "domain": "string",        "name": "string",        "logoUrl": "string",        "faviconUrl": "string",        "countryCode": "string",        "monthlyVisits": 0,        "trafficGrowth30d": 0,        "productsCount": 0,        "googleCategoryIds": [          0        ]      },      "pin": {        "isCurrent": true,        "firstPinnedAt": "string",        "lastPinnedAt": "string",        "lastUnpinnedAt": "string"      },      "pageSnapshot": {        "recordedAt": "string",        "adsCount": 0,        "organicCount": 0,        "totalTikToks": 0,        "dailyViews": 0,        "dailyLikes": 0,        "dailyFollowers": 0      },      "indexedAt": "string"    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 250,    "totalPages": 10  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

Get a TikTok library item

Returns one TikTok library item detail by composite_ad_id, with tiktok_id fallback because tiktok_id is part of the tiktoks-search public ES contract.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

itemId*string

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/tiktok/library/tiktok_7078586231734521093"

{  "requestId": "req_123",  "data": {    "id": "tiktok_7078586231734521093",    "tiktokId": "string",    "type": "ad",    "status": "active",    "isPinned": true,    "publishedAt": "string",    "createdAt": "string",    "updatedAt": "string",    "daysRunning": 0,    "media": {      "type": "video",      "thumbnailUrl": "string",      "mediaUrl": "string",      "videoUrl": "string",      "imageUrls": [        "string"      ],      "medias": [        {          "type": "video",          "url": "string",          "order": 0        }      ],      "durationSec": 0,      "mediaCount": 0,      "imageCount": 0    },    "content": {      "description": "string",      "language": "string",      "category": "string",      "hashtags": [        "string"      ],      "music": {        "id": "string",        "title": "string",        "author": "string"      }    },    "metrics": {      "views": 0,      "likes": 0,      "comments": 0,      "saves": 0,      "shares": 0,      "reposts": 0,      "engagementRate": 0,      "rank": 0,      "rankPercent": 0,      "relevanceScore": 0,      "deltaRank3d": 0,      "deltaRank7d": 0,      "deltaRank14d": 0,      "deltaRank30d": 0    },    "profile": {      "id": "string",      "handle": "string",      "name": "string",      "avatarUrl": "string",      "bio": "string",      "bioUrl": "string",      "accountType": "string",      "secUid": "string",      "followers": 0,      "following": 0,      "totalTikToks": 0,      "newTikToks": 0,      "percentAds": 0,      "views": 0,      "likes": 0,      "pageCreation": "string"    },    "shop": {      "id": "string",      "domain": "string",      "name": "string",      "logoUrl": "string",      "faviconUrl": "string",      "countryCode": "string",      "monthlyVisits": 0,      "trafficGrowth30d": 0,      "productsCount": 0,      "googleCategoryIds": [        0      ]    },    "pin": {      "isCurrent": true,      "firstPinnedAt": "string",      "lastPinnedAt": "string",      "lastUnpinnedAt": "string"    },    "pageSnapshot": {      "recordedAt": "string",      "adsCount": 0,      "organicCount": 0,      "totalTikToks": 0,      "dailyViews": 0,      "dailyLikes": 0,      "dailyFollowers": 0    },    "indexedAt": "string",    "links": {      "tiktokUrl": "string",      "profileUrl": "string"    },    "source": {      "network": "string",      "sourceType": "string",      "tiktokPageId": "string",      "websiteId": "string",      "domain": "string"    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

List TikTok library items for a shop

Returns TikTok library items linked to one public shop id using exact ES shop identifiers. This route has a TikTok endpoint key and ads entitlement even though it is nested under /v1/shops.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

shopId*string

Stable public shop identifier.

Query Parameters

search?string

searchArea?string

Default"all"

Value in"all" | "caption" | "profile" | "hashtag" | "music"

type?string

Default"all"

Value in"all" | "ad" | "organic"

status?string

Default"all"

Value in"all" | "active" | "inactive"

mediaTypes?array<>

languages?array<string>

ISO 639-1 codes (en, fr) or English language names (English, french), case-insensitive.

countries?array<string>

hashtags?array<string>

Hashtags with or without #, case-insensitive.

tiktokPageId?string

domain?string

handle?string

publishedAfter?string

publishedBefore?string

minViews?number

maxViews?number

minEngagementRate?number

maxEngagementRate?number

sortBy?string

Default"newest"

Value in

"relevance" | "newest" | "updatedAt" | "views" | "likes" | "comments" | "shares" | "saves" | "engagementRate" | "daysRunning" | "followers"

order?string

Default"desc"

Value in"asc" | "desc"

page?object

Default1

Range1 <= value

limit?object

Default25

Range1 <= value <= 50

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/shops/3f8aa146-6f96-46e8-9781-64db5166f9a8/tiktok/library"

{  "requestId": "req_123",  "data": [    {      "id": "tiktok_7078586231734521093",      "tiktokId": "string",      "type": "ad",      "status": "active",      "isPinned": true,      "publishedAt": "string",      "createdAt": "string",      "updatedAt": "string",      "daysRunning": 0,      "media": {        "type": "video",        "thumbnailUrl": "string",        "mediaUrl": "string",        "videoUrl": "string",        "imageUrls": [          "string"        ],        "medias": [          {            "type": "video",            "url": "string",            "order": 0          }        ],        "durationSec": 0,        "mediaCount": 0,        "imageCount": 0      },      "content": {        "description": "string",        "language": "string",        "category": "string",        "hashtags": [          "string"        ],        "music": {          "id": "string",          "title": "string",          "author": "string"        }      },      "metrics": {        "views": 0,        "likes": 0,        "comments": 0,        "saves": 0,        "shares": 0,        "reposts": 0,        "engagementRate": 0,        "rank": 0,        "rankPercent": 0,        "relevanceScore": 0,        "deltaRank3d": 0,        "deltaRank7d": 0,        "deltaRank14d": 0,        "deltaRank30d": 0      },      "profile": {        "id": "string",        "handle": "string",        "name": "string",        "avatarUrl": "string",        "bio": "string",        "bioUrl": "string",        "accountType": "string",        "secUid": "string",        "followers": 0,        "following": 0,        "totalTikToks": 0,        "newTikToks": 0,        "percentAds": 0,        "views": 0,        "likes": 0,        "pageCreation": "string"      },      "shop": {        "id": "string",        "domain": "string",        "name": "string",        "logoUrl": "string",        "faviconUrl": "string",        "countryCode": "string",        "monthlyVisits": 0,        "trafficGrowth30d": 0,        "productsCount": 0,        "googleCategoryIds": [          0        ]      },      "pin": {        "isCurrent": true,        "firstPinnedAt": "string",        "lastPinnedAt": "string",        "lastUnpinnedAt": "string"      },      "pageSnapshot": {        "recordedAt": "string",        "adsCount": 0,        "organicCount": 0,        "totalTikToks": 0,        "dailyViews": 0,        "dailyLikes": 0,        "dailyFollowers": 0      },      "indexedAt": "string"    }  ],  "pagination": {    "page": 1,    "limit": 25,    "total": 250,    "totalPages": 10  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

{  "error": {    "code": "missing_api_key",    "message": "Provide an API key using Authorization: Bearer <api_key>.",    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",    "details": {      "validationErrors": [        {          "field": "query-string.limit",          "location": "query-string",          "expected": [            "limit must not be greater than 100"          ]        }      ]    }  }}

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`