Social Fetch
Dashboard
TikTok

Get TikTok Ad Library ad

Get a single TikTok Ad Library or Top Ads creative by ad id or public ad URL.

Try in Playground
GET/v1/tiktok/ad-library/ads
1credit

Headers

Get your API key
x-api-keystringheader

API key (`sfk_...`)

Parameters
2
adIdstringquery

TikTok Ad Library or Top Ads ad id.

min 1 chars · max 4096 chars

urlstringquery

Public TikTok Ad Library or Top Ads detail URL for the ad.

min 1 chars · max 4096 chars

Response fields
139

Endpoint-specific response payload.

datalookupStatus
string

Whether the ad was found.

one of: found, not_found

Ad details when found; otherwise null.

dataadid
string

Stable identifier for the ad.

min 1 chars

dataadtitle
stringnullable

Ad title or caption when available.

dataadbrandName
stringnullable

Brand or advertiser name when available.

dataadcost
numbernullable

Relative cost signal when available.

dataadctr
numbernullable

Click-through rate when available.

dataadlikeCount
integernullable

Like count when available.

≥ 0

dataadindustryKey
stringnullable

Industry key reported for the ad when available.

dataadobjective
stringnullable

Campaign objective key when available.

dataadurl
stringnullable

Public TikTok Ads Library detail URL when available.

dataadfirstShownAt
stringnullable

ISO-8601 timestamp for when the ad was first shown, when available.

dataadlastShownAt
stringnullable

ISO-8601 timestamp for when the ad was last shown, when available.

dataadestimatedAudience
stringnullable

Estimated audience band when available.

Video creative when available.

dataadvideoid
stringnullable

Video id when available.

dataadvideodurationSeconds
numbernullable

Video duration in seconds when available.

dataadvideocoverUrl
stringnullable

Cover image URL when available.

dataadvideowidth
integernullable

Video width in pixels when available.

≥ 0

dataadvideoheight
integernullable

Video height in pixels when available.

≥ 0

Playback URLs by resolution when available.

dataadvideourlsp360
stringnullable

360p video URL when available.

dataadvideourlsp480
stringnullable

480p video URL when available.

dataadvideourlsp540
stringnullable

540p video URL when available.

dataadvideourlsp720
stringnullable

720p video URL when available.

dataadvideourlsp1080
stringnullable

1080p video URL when available.

dataadcommentCount
integernullable

Comment count when available.

≥ 0

dataadshareCount
integernullable

Share count when available.

≥ 0

Countries associated with the ad when available.

dataadcountries[]
stringoptional

min 1 chars

dataadlandingPageUrl
stringnullable

Landing page URL when available.

Keywords associated with the ad when available.

dataadkeywords[]
stringoptional

min 1 chars

Campaign objectives reported for the ad.

dataadobjectives[]label
stringnullable

Objective label when available.

dataadobjectives[]value
numbernullable

Objective value when available.

Creative pattern labels when available.

dataadpatterns[]
stringoptional

min 1 chars

dataadsource
stringnullable

Reported ad source when available.

dataadhasVoiceOver
booleannullable

Whether the ad includes a voice-over when known.

dataaddetailUrl
stringnullable

Public TikTok ad detail URL when available.

Second-by-second interactive analysis when available.

Click-through retention analysis when available.

dataadinteractiveAnalysisctrmetric
stringnullable

Metric name when available.

Second-by-second metric samples.

dataadinteractiveAnalysisctranalysis[]second
integer

Second offset within the ad video.

≥ 0

dataadinteractiveAnalysisctranalysis[]value
number

Metric value at this second.

dataadinteractiveAnalysisctrduration
integernullable

Analysis duration in seconds when available.

≥ 0

Highlighted second offsets for this metric.

dataadinteractiveAnalysisctrhighlight[]
integeroptional

≥ 0

dataadinteractiveAnalysisctrpercentile
numbernullable

Percentile ranking for this metric when available.

Conversion retention analysis when available.

dataadinteractiveAnalysiscvrmetric
stringnullable

Metric name when available.

Second-by-second metric samples.

dataadinteractiveAnalysiscvranalysis[]second
integer

Second offset within the ad video.

≥ 0

dataadinteractiveAnalysiscvranalysis[]value
number

Metric value at this second.

dataadinteractiveAnalysiscvrduration
integernullable

Analysis duration in seconds when available.

≥ 0

Highlighted second offsets for this metric.

dataadinteractiveAnalysiscvrhighlight[]
integeroptional

≥ 0

dataadinteractiveAnalysiscvrpercentile
numbernullable

Percentile ranking for this metric when available.

Click count analysis when available.

dataadinteractiveAnalysisclicksmetric
stringnullable

Metric name when available.

Second-by-second metric samples.

dataadinteractiveAnalysisclicksanalysis[]second
integer

Second offset within the ad video.

≥ 0

dataadinteractiveAnalysisclicksanalysis[]value
number

Metric value at this second.

dataadinteractiveAnalysisclicksduration
integernullable

Analysis duration in seconds when available.

≥ 0

Highlighted second offsets for this metric.

dataadinteractiveAnalysisclickshighlight[]
integeroptional

≥ 0

dataadinteractiveAnalysisclickspercentile
numbernullable

Percentile ranking for this metric when available.

Conversion count analysis when available.

dataadinteractiveAnalysisconversionmetric
stringnullable

Metric name when available.

Second-by-second metric samples.

dataadinteractiveAnalysisconversionanalysis[]second
integer

Second offset within the ad video.

≥ 0

dataadinteractiveAnalysisconversionanalysis[]value
number

Metric value at this second.

dataadinteractiveAnalysisconversionduration
integernullable

Analysis duration in seconds when available.

≥ 0

Highlighted second offsets for this metric.

dataadinteractiveAnalysisconversionhighlight[]
integeroptional

≥ 0

dataadinteractiveAnalysisconversionpercentile
numbernullable

Percentile ranking for this metric when available.

Playback retention analysis when available.

dataadinteractiveAnalysisremainmetric
stringnullable

Metric name when available.

Second-by-second metric samples.

dataadinteractiveAnalysisremainanalysis[]second
integer

Second offset within the ad video.

≥ 0

dataadinteractiveAnalysisremainanalysis[]value
number

Metric value at this second.

dataadinteractiveAnalysisremainduration
integernullable

Analysis duration in seconds when available.

≥ 0

Highlighted second offsets for this metric.

dataadinteractiveAnalysisremainhighlight[]
integeroptional

≥ 0

dataadinteractiveAnalysisremainpercentile
numbernullable

Percentile ranking for this metric when available.

Related ads recommended alongside this ad.

dataadrelatedAds[]id
string

Stable identifier for the ad.

min 1 chars

dataadrelatedAds[]title
stringnullable

Ad title or caption when available.

dataadrelatedAds[]brandName
stringnullable

Brand or advertiser name when available.

dataadrelatedAds[]cost
numbernullable

Relative cost signal when available.

dataadrelatedAds[]ctr
numbernullable

Click-through rate when available.

dataadrelatedAds[]likeCount
integernullable

Like count when available.

≥ 0

dataadrelatedAds[]industryKey
stringnullable

Industry key reported for the ad when available.

dataadrelatedAds[]objective
stringnullable

Campaign objective key when available.

dataadrelatedAds[]url
stringnullable

Public TikTok Ads Library detail URL when available.

dataadrelatedAds[]firstShownAt
stringnullable

ISO-8601 timestamp for when the ad was first shown, when available.

dataadrelatedAds[]lastShownAt
stringnullable

ISO-8601 timestamp for when the ad was last shown, when available.

dataadrelatedAds[]estimatedAudience
stringnullable

Estimated audience band when available.

Video creative when available.

dataadrelatedAds[]videoid
stringnullable

Video id when available.

dataadrelatedAds[]videodurationSeconds
numbernullable

Video duration in seconds when available.

dataadrelatedAds[]videocoverUrl
stringnullable

Cover image URL when available.

dataadrelatedAds[]videowidth
integernullable

Video width in pixels when available.

≥ 0

dataadrelatedAds[]videoheight
integernullable

Video height in pixels when available.

≥ 0

Playback URLs by resolution when available.

dataadrelatedAds[]videourlsp360
stringnullable

360p video URL when available.

dataadrelatedAds[]videourlsp480
stringnullable

480p video URL when available.

dataadrelatedAds[]videourlsp540
stringnullable

540p video URL when available.

dataadrelatedAds[]videourlsp720
stringnullable

720p video URL when available.

dataadrelatedAds[]videourlsp1080
stringnullable

1080p video URL when available.

dataadadvertiserBusinessId
stringnullable

TikTok business ID of the ad's advertiser when available. Pass it as `advertiserBusinessId` with `advertiserName` to search only that advertiser.

dataadformat
stringnullable

Creative format: `video` for video ads, `images` for photo or carousel ads. Null when no creative is reported.

one of: video, images, null

Every video creative reported for the ad. `video` is the first entry. Empty for image ads.

dataadvideos[]id
stringnullable

Video id when available.

dataadvideos[]durationSeconds
numbernullable

Video duration in seconds when available.

dataadvideos[]coverUrl
stringnullable

Cover image URL when available.

dataadvideos[]width
integernullable

Video width in pixels when available.

≥ 0

dataadvideos[]height
integernullable

Video height in pixels when available.

≥ 0

Playback URLs by resolution when available.

dataadvideos[]urlsp360
stringnullable

360p video URL when available.

dataadvideos[]urlsp480
stringnullable

480p video URL when available.

dataadvideos[]urlsp540
stringnullable

540p video URL when available.

dataadvideos[]urlsp720
stringnullable

720p video URL when available.

dataadvideos[]urlsp1080
stringnullable

1080p video URL when available.

Image URLs for photo or carousel ads, in display order. Empty for video ads.

dataadimageUrls[]
stringoptional

min 1 chars

dataadcategory
stringnullable

Ad category as TikTok labels it, such as `News & Entertainment`, when available.

TikTok's review information for the ad.

dataadmoderationauditStatus
stringnullable

Review status code exactly as TikTok reports it, such as `1`. TikTok does not document these codes. Null when not reported.

dataadmoderationrejectionReason
stringnullable

Rejection details as TikTok reports them, when the ad was rejected. Null otherwise.

dataadisUnavailable
booleannullable

Whether TikTok reports the ad as no longer available, when known.

Metadata describing the request and billing outcome.

metarequestId
string

Unique request identifier for tracing this API call.

min 1 chars

metacreditsCharged
integer

Credits charged for this request.

≥ 0

metaversion
string

Public API version that served the response.

one of: v1

metacached
booleanoptional

True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.

Code example

curl "https://api.socialfetch.dev/v1/tiktok/ad-library/ads?adId=1872975048695249" \
  -H "x-api-key: YOUR_API_KEY"

Responses

TikTok Ad Library ad.

Showcase products

List products featured on a creator's TikTok showcase by handle.

Ad search

Search the public TikTok Ads Library by keyword or advertiser name.