{ "openapi": "3.1.0", "info": { "title": "TikTok Ad Library API", "version": "1.0.0", "description": "Public TikTok ads, downloadable video creative, advertiser identity and EU reach and targeting disclosures exposed through FetchLayer." }, "servers": [ { "url": "https://api.fetchlayer.dev/tiktok-ad-library" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search-ads": { "post": { "operationId": "search-ads", "tags": [ "Ads" ], "summary": "Search ads by keyword", "description": "Search the TikTok Ad Library for public short-form video ads matching a keyword or phrase. Filter by country, ad status, media type, audience age bracket, audience gender, reach band and the dates the ad was shown, and page through the results with a cursor. Set queryMode to advertiser_name to match advertiser names instead of ad content. There is no political-ad filter, because TikTok prohibits political advertising outright.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Keyword or phrase to search the TikTok Ad Library for." }, "queryMode": { "type": "string", "description": "Match the query against ad content (keyword) or against advertiser names (advertiser_name).", "example": "keyword" }, "exactPhrase": { "type": "boolean", "description": "Match the query as a whole phrase instead of loose terms.", "example": "false" }, "country": { "type": "string", "description": "Two-letter country code, or ALL for every covered country. The library covers 33 countries only — the 27 EU member states plus GB, CH, NO, IS, LI and TR. Any other country (including US, CA and AU) is rejected.", "example": "ALL" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Several covered countries at once (max 33). Overrides country." }, "adStatus": { "type": "string", "description": "all, active, or inactive.", "example": "active" }, "mediaType": { "type": "string", "description": "all, video, image, or text. There is no political-ad filter: TikTok prohibits political advertising outright.", "example": "all" }, "ages": { "type": "array", "items": { "type": "string" }, "description": "Audience age brackets the ad was targeted at: 13-17, 18-24, 25-34, 35-44, 45-54, 55+, or all." }, "reach": { "type": "array", "items": { "type": "string" }, "description": "Reach band the ad landed in: under_10k, 10k_to_100k, over_100k, or all." }, "gender": { "type": "string", "description": "Audience gender the ad was targeted at: all, female, or male.", "example": "all" }, "shownFrom": { "type": "string", "description": "Only ads shown on or after this YYYY-MM-DD date.", "example": "30 days before shownTo" }, "shownTo": { "type": "string", "description": "Only ads shown on or before this YYYY-MM-DD date.", "example": "today" }, "limit": { "type": "number", "description": "Maximum ads returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed. Each page walked bills as one request." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "sortBy": { "type": "string", "description": "last_shown_date or unique_users_seen.", "example": "last_shown_date" }, "sortDirection": { "type": "string", "description": "asc or desc.", "example": "desc" } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "skincare routine", "country": "DE", "adStatus": "active", "mediaType": "video", "limit": 30 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "additionalProperties": true, "description": "The filters this search actually ran with, after defaults were applied — including the date window, which defaults to the last 30 days rather than all time." }, "ads": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "adId": { "type": "string", "description": "Ad id — the handle for ad-detail and ad-media." }, "adLibraryUrl": { "type": "string", "description": "Public TikTok Ad Library permalink for this ad." }, "isActive": { "type": "boolean", "description": "Whether the ad was still being shown at the end of the requested date window." }, "firstShownDate": { "type": "string", "description": "First day the ad was shown, YYYY-MM-DD. Also available as firstShownDateUnixMs." }, "lastShownDate": { "type": "string", "description": "Last day the ad was shown, YYYY-MM-DD. Longevity is the usual proxy for what is working." }, "estimatedAudience": { "type": "string", "description": "Published as a band, for example \"10K-100K\". Never an exact figure." }, "uniqueUsersSeen": { "type": "number", "description": "Unique people reached, where the library publishes it. Null where it does not." }, "spend": { "type": "string", "description": "Published only where the law requires it, so null for ordinary commercial ads." }, "advertiser": { "type": "object", "additionalProperties": true, "description": "Advertiser id, registered business name and location, sponsor (\"paid for by\"), plus the linked account: username, display name, URL, avatar, follower count and account type." }, "creative": { "type": "object", "additionalProperties": true, "description": "Ad text, call to action, landing page URL, advertising objective, video files with cover frames, image URLs, and the media type the ad actually carries." }, "rejectionReason": { "type": "string", "description": "Why the ad was removed, when it was." } } }, "description": "The matching ads, most recently shown first unless sortBy says otherwise." }, "adCount": { "type": "number", "description": "Number of ads in this response." }, "totalMatches": { "type": "number", "description": "Total ads matching the filters, which can exceed adCount. Null when the library does not publish it." }, "pagesScraped": { "type": "number", "description": "Pages actually walked. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages asked for. Lower pagesScraped means the walk stopped early — read notes to find out why." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue from where this response stopped. Null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, an upstream cap, a filter the library could not honour. Read it before treating a result set as complete." } }, "additionalProperties": false }, "examples": { "default": { "value": { "adCount": 30, "totalMatches": 412, "pagesScraped": 1, "hasNextPage": true, "notes": [], "ads": [ { "adId": "1794523310028321", "adLibraryUrl": "https://library.tiktok.com/ads/detail/?ad_id=1794523310028321", "isActive": true, "firstShownDate": "2026-08-19", "lastShownDate": "2026-09-11", "estimatedAudience": "100K-1M", "advertiser": { "advertiserId": "7203119844", "name": "Acme Beauty GmbH", "registeredLocation": "DE", "accountUsername": "acmebeauty" }, "creative": { "title": "Three steps. Two minutes.", "callToAction": "Shop now", "mediaType": "video" } } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/advertiser-ads": { "post": { "operationId": "advertiser-ads", "tags": [ "Ads" ], "summary": "Get every ad one advertiser has run", "description": "Return the TikTok Ad Library ads for a single advertiser, given their registered business name or an ad library URL naming one. Accepts the same filters as a keyword search. Advertisers are scoped by registered name here, not by handle — run search-advertisers first to get the exact name, or pass advertiserId if you already hold one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser": { "type": "string", "description": "Registered advertiser name, or an ad library URL naming one. Use search-advertisers to find the exact name." }, "advertiserId": { "type": "string", "description": "The advertiser's numeric id, when search-advertisers has already returned one." }, "country": { "type": "string", "description": "Two-letter country code, or ALL for every covered country. The library covers 33 countries only — the 27 EU member states plus GB, CH, NO, IS, LI and TR. Any other country (including US, CA and AU) is rejected.", "example": "ALL" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Several covered countries at once (max 33). Overrides country." }, "adStatus": { "type": "string", "description": "all, active, or inactive.", "example": "active" }, "mediaType": { "type": "string", "description": "all, video, image, or text. There is no political-ad filter: TikTok prohibits political advertising outright.", "example": "all" }, "ages": { "type": "array", "items": { "type": "string" }, "description": "Audience age brackets the ad was targeted at: 13-17, 18-24, 25-34, 35-44, 45-54, 55+, or all." }, "reach": { "type": "array", "items": { "type": "string" }, "description": "Reach band the ad landed in: under_10k, 10k_to_100k, over_100k, or all." }, "gender": { "type": "string", "description": "Audience gender the ad was targeted at: all, female, or male.", "example": "all" }, "shownFrom": { "type": "string", "description": "Only ads shown on or after this YYYY-MM-DD date.", "example": "30 days before shownTo" }, "shownTo": { "type": "string", "description": "Only ads shown on or before this YYYY-MM-DD date.", "example": "today" }, "limit": { "type": "number", "description": "Maximum ads returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed. Each page walked bills as one request." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "sortBy": { "type": "string", "description": "last_shown_date or unique_users_seen.", "example": "last_shown_date" }, "sortDirection": { "type": "string", "description": "asc or desc.", "example": "desc" } }, "additionalProperties": false, "required": [ "advertiser" ] }, "examples": { "default": { "value": { "advertiser": "Acme Beauty GmbH", "country": "DE", "adStatus": "all", "pages": 3 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiserName": { "type": "string", "description": "The resolved registered advertiser name." }, "advertiserId": { "type": "string", "description": "The resolved advertiser id, where the library exposes one." }, "ads": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "adId": { "type": "string", "description": "Ad id — the handle for ad-detail and ad-media." }, "adLibraryUrl": { "type": "string", "description": "Public TikTok Ad Library permalink for this ad." }, "isActive": { "type": "boolean", "description": "Whether the ad was still being shown at the end of the requested date window." }, "firstShownDate": { "type": "string", "description": "First day the ad was shown, YYYY-MM-DD. Also available as firstShownDateUnixMs." }, "lastShownDate": { "type": "string", "description": "Last day the ad was shown, YYYY-MM-DD. Longevity is the usual proxy for what is working." }, "estimatedAudience": { "type": "string", "description": "Published as a band, for example \"10K-100K\". Never an exact figure." }, "uniqueUsersSeen": { "type": "number", "description": "Unique people reached, where the library publishes it. Null where it does not." }, "spend": { "type": "string", "description": "Published only where the law requires it, so null for ordinary commercial ads." }, "advertiser": { "type": "object", "additionalProperties": true, "description": "Advertiser id, registered business name and location, sponsor (\"paid for by\"), plus the linked account: username, display name, URL, avatar, follower count and account type." }, "creative": { "type": "object", "additionalProperties": true, "description": "Ad text, call to action, landing page URL, advertising objective, video files with cover frames, image URLs, and the media type the ad actually carries." }, "rejectionReason": { "type": "string", "description": "Why the ad was removed, when it was." } } }, "description": "The matching ads, most recently shown first unless sortBy says otherwise." }, "adCount": { "type": "number", "description": "Number of ads in this response." }, "totalMatches": { "type": "number", "description": "Total ads matching the filters, which can exceed adCount. Null when the library does not publish it." }, "pagesScraped": { "type": "number", "description": "Pages actually walked. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages asked for. Lower pagesScraped means the walk stopped early — read notes to find out why." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue from where this response stopped. Null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a truncated walk, an upstream cap, a filter the library could not honour. Read it before treating a result set as complete." } }, "additionalProperties": false }, "examples": { "default": { "value": { "advertiserName": "Acme Beauty GmbH", "advertiserId": "7203119844", "adCount": 84, "pagesScraped": 3, "hasNextPage": false, "notes": [], "ads": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/search-advertisers": { "post": { "operationId": "search-advertisers", "tags": [ "Advertisers" ], "summary": "Find advertisers by name", "description": "Look up the registered advertiser names matching a brand or company name, with the ids and library URLs the other routes accept. Names are matched as registered, so one brand can appear as several legal entities — an advertiser lookup needs the exact name, and this is how you get it. This endpoint takes no country or date filters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Advertiser or brand name to look up." }, "limit": { "type": "number", "description": "Maximum advertisers returned (max 50), or -1 for everything available.", "example": "20" } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "Acme Beauty", "limit": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "advertisers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "advertiserId": { "type": "string", "description": "Advertiser id — pass it to advertiser-ads or advertiser-profile as advertiserId." }, "name": { "type": "string", "description": "Registered advertiser name, exactly as the other routes expect it." }, "adLibraryUrl": { "type": "string", "description": "Library listing scoped to this advertiser." } } }, "description": "Matching registered advertisers." }, "advertiserCount": { "type": "number", "description": "Number of advertisers in this response." }, "suggestedKeywords": { "type": "array", "items": { "type": "string" }, "description": "Keyword suggestions the library returns alongside the advertiser matches." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this result, such as a match list the library truncated." } }, "additionalProperties": false }, "examples": { "default": { "value": { "advertiserCount": 2, "suggestedKeywords": [ "acme beauty serum" ], "advertisers": [ { "advertiserId": "7203119844", "name": "Acme Beauty GmbH", "adLibraryUrl": "https://library.tiktok.com/ads?adv_name=Acme%20Beauty%20GmbH" } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/advertiser-profile": { "post": { "operationId": "advertiser-profile", "tags": [ "Advertisers" ], "summary": "Get an advertiser's profile", "description": "Read an advertiser's identity: registered business name and location, who paid for their ads, the linked TikTok account with its follower count and verification type, how many ads they published in the requested window, and the countries those ads ran in. The TikTok Ad Library has no advertiser endpoint of its own — it publishes identity per ad — so this profile is assembled from the advertiser's latest matching ad, and sampledAdId names the ad it was read from.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser": { "type": "string", "description": "Registered advertiser name, or an ad library URL naming one." }, "country": { "type": "string", "description": "Two-letter country code, or ALL for every covered country. The library covers 33 countries only — the 27 EU member states plus GB, CH, NO, IS, LI and TR. Any other country (including US, CA and AU) is rejected.", "example": "ALL" } }, "additionalProperties": false, "required": [ "advertiser" ] }, "examples": { "default": { "value": { "advertiser": "Acme Beauty GmbH", "country": "DE" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "additionalProperties": true, "description": "The advertiser's identity record, assembled from their latest matching ad.", "properties": { "advertiserId": { "type": "string", "description": "Advertiser id." }, "name": { "type": "string", "description": "Registered business name." }, "registeredLocation": { "type": "string", "description": "Country the business is registered in." }, "sponsor": { "type": "string", "description": "Who paid for the ads, where it differs from the advertiser." }, "accountUsername": { "type": "string", "description": "Linked TikTok account handle. Also accountDisplayName, accountUrl and avatarUrl." }, "followerCount": { "type": "string", "description": "As published, for example \"150.2K\". A rounded figure, not an exact count." }, "accountType": { "type": "string", "description": "For example VERIFIED_BA for a verified business account." }, "adCount": { "type": "number", "description": "Ads published for this advertiser over the requested date window — not their lifetime total." }, "countriesShown": { "type": "array", "items": { "type": "string" }, "description": "Countries this advertiser's sampled ads were shown in." }, "sampledAdId": { "type": "string", "description": "The ad the identity details were read from, since the library publishes them per ad." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this result, such as an identity assembled from a thin sample." } }, "additionalProperties": false }, "examples": { "default": { "value": { "profile": { "advertiserId": "7203119844", "name": "Acme Beauty GmbH", "registeredLocation": "DE", "accountUsername": "acmebeauty", "followerCount": "150.2K", "accountType": "VERIFIED_BA", "adCount": 84, "countriesShown": [ "DE", "AT", "CH" ], "sampledAdId": "1794523310028321" } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/ad-detail": { "post": { "operationId": "ad-detail", "tags": [ "Ads" ], "summary": "Get one ad in full", "description": "Read everything the TikTok Ad Library publishes for a single ad: the creative and ad copy, the call to action, the landing page, the advertising objective, the advertiser’s identity and registered location, who paid for it, and the targeting and reach breakdown by region, age bracket and gender. Reach and targeting disclosures are published for European countries; ads elsewhere come back with targeting null.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ad": { "type": "string", "description": "Ad id, or an ad library URL containing one." } }, "additionalProperties": false, "required": [ "ad" ] }, "examples": { "default": { "value": { "ad": "1794523310028321" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "adId": { "type": "string", "description": "The resolved ad id." }, "ad": { "type": "object", "additionalProperties": true, "description": "The full ad record, including its creative. Null when the ad is no longer published." }, "advertiserProfile": { "type": "object", "additionalProperties": true, "description": "Identity of the advertiser running the ad, read from this ad." }, "targeting": { "type": "object", "additionalProperties": true, "description": "The targeting the advertiser chose and the reach it produced. Null on ads that carry no disclosure.", "properties": { "totalImpressions": { "type": "string", "description": "Total reach across all regions, as published — a band or a rounded figure, never an exact count." }, "reachByRegion": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Per-region reach, each with breakdowns by age bracket and gender." }, "ageTargetingByRegion": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Age brackets the advertiser targeted, per region. genderTargetingByRegion mirrors it." }, "targetAudienceSize": { "type": "string", "description": "Size of the audience the targeting could reach, as published, for example \"35.9M-43.9M\"." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Also cities, provinces, languages, deviceModels and operatingSystems, where disclosed." }, "usesAudienceTargeting": { "type": "string", "description": "Whether a custom audience list was used. audienceExcluded, highSpendingPower, interests, videoInteractions and creatorInteractions sit alongside it." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this result, such as a disclosure the library withheld." } }, "additionalProperties": false }, "examples": { "default": { "value": { "adId": "1794523310028321", "ad": { "creative": { "title": "Three steps. Two minutes.", "callToAction": "Shop now", "landingPageUrl": "https://example.com", "advertisingObjective": "Sales", "mediaType": "video" } }, "targeting": { "totalRegions": 3, "totalImpressions": "100K-1M", "targetAudienceSize": "35.9M-43.9M", "countries": [ "DE", "AT", "CH" ] } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/ad-media": { "post": { "operationId": "ad-media", "tags": [ "Media" ], "summary": "Get an ad's videos and images", "description": "Resolve an ad's creative into downloadable files — the video, its cover frame, and any images. The library's own URLs are signed and expire within hours, so each asset also carries a downloadUrl served through FetchLayer that does not. Optionally probe each asset to confirm it is still retrievable and report its size and content type, or inline it as base64 for assets under the inline size limit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ad": { "type": "string", "description": "Ad id, or an ad library URL containing one." }, "kinds": { "type": "array", "items": { "type": "string" }, "description": "video, image, and/or thumbnail.", "example": "all three" }, "probe": { "type": "boolean", "description": "Confirm each asset is still downloadable and report its size and content type." }, "inline": { "type": "boolean", "description": "Return the bytes base64-encoded. Refused for assets over the inline size limit." } }, "additionalProperties": false, "required": [ "ad" ] }, "examples": { "default": { "value": { "ad": "1794523310028321", "kinds": [ "video", "thumbnail" ], "probe": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "adId": { "type": "string", "description": "The resolved ad id." }, "assets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "description": "video, image, or thumbnail." }, "url": { "type": "string", "description": "The file's own URL on TikTok. Signed, and expires within hours." }, "downloadUrl": { "type": "string", "description": "Serves the same file through GET /media, without the expiry." }, "quality": { "type": "string", "description": "original or cover." }, "contentType": { "type": "string", "description": "MIME type. Populated only when probe or inline was set." }, "contentLength": { "type": "number", "description": "Size in bytes. Populated only when probe or inline was set." }, "base64": { "type": "string", "description": "The bytes themselves. Populated only when inline was set." } } }, "description": "The ad's media assets." }, "assetCount": { "type": "number", "description": "Number of assets in this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this result, such as an asset that could not be probed." } }, "additionalProperties": false }, "examples": { "default": { "value": { "assetCount": 2, "assets": [ { "kind": "video", "quality": "original", "contentType": "video/mp4", "contentLength": 4182773, "url": "https://v16m.tiktokcdn.com/..." } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/media": { "get": { "operationId": "media", "tags": [ "Media" ], "summary": "Download an ad media file", "description": "Stream an ad's actual video or image bytes, using a url taken from an asset returned by /ad-media. Only TikTok's own media hosts are accepted. HTTP Range requests are supported, so video seeking works in a player. This is a GET with query parameters, not a JSON POST, and it bills as one request.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "TikTok media URL, as returned on an ad asset. Passed as a query parameter.", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Content-Disposition filename to serve the file as (max 200 characters).", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Standard HTTP Range request header, for example bytes=0-65535. Sent as a header, not a query parameter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse a TikTok Ad Library URL", "description": "Turn any TikTok Ad Library URL into the structured filters it encodes — whether it points at one ad, one advertiser or a search, plus the country, status, media type, audience and date filters carried in its query string. A filter the URL leaves out comes back null or empty rather than defaulted, so you can tell what was actually specified. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any TikTok Ad Library URL, to be parsed into structured filters." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://library.tiktok.com/ads?region=DE&adv_name=Acme%20Beauty%20GmbH&type=1" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "description": "What the URL points at: ad, advertiser, search, or unknown." }, "adId": { "type": "string", "description": "Present when target is ad." }, "advertiserName": { "type": "string", "description": "Present when target is advertiser. advertiserId sits alongside it." }, "query": { "type": "string", "description": "Present when target is search or advertiser. queryMode says which field it matched." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Country filters carried in the URL. Empty when the URL specifies none." }, "adStatus": { "type": "string", "description": "Status filter carried in the URL, or null." }, "mediaType": { "type": "string", "description": "Media type filter carried in the URL, or null." }, "ages": { "type": "array", "items": { "type": "string" }, "description": "Audience age filters carried in the URL. reach and gender sit alongside it." }, "shownFrom": { "type": "string", "description": "Date window carried in the URL, YYYY-MM-DD. shownTo, sortBy and sortDirection sit alongside it." } }, "additionalProperties": false }, "examples": { "default": { "value": { "target": "advertiser", "advertiserName": "Acme Beauty GmbH", "countries": [ "DE" ], "adStatus": null, "ages": [], "query": null } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }