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<>

Itemsitems <= 20

countries?array<>

Itemsitems <= 20

hashtags?array<>

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>

countries?array<string>

categories?array<string>

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>

countries?array<string>

hashtags?array<string>

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`