Query Ads
Use POST /v2/research/adlib/ad/query to query ads.
HTTP URL | https://open.tiktokapis.com/v2/research/adlib/ad/query/ |
HTTP Method | POST |
Scopes | research.adlib.basic |
Request
Headers
Key | Type | Description | Example | Required |
Authorization | string | The token that bears the authorization of the TikTok user, which is obtained through /v2/oauth/token/. | Bearer clt.example12345Example12345Example | true |
Content-Type | string | The original media type of the resource. | application/json | true |
Query parameters
Key | Type | Description | Example | Required |
fields | string | The requested fields:
| ad.id, ad.first_shown_date, ad.last_shown_date | true |
Body
Key | Type | Description | Example | Required |
filters | RequestFilters | The filters that will be applied to the query. | See the "Request example" section below | true |
search_term | string | The terms to search for in the query. The limit of the string is 50 characters or less. | mobile games | false |
search_type | string | The search type (which is case insensitive):
| fuzzy_phrase | false |
max_count | i64 | The maximum number of results returned at once. The default value is 10 and the maximum value is 10. | 10 | false |
search_id | string | A search_id is a unique identifier assigned to a cached search result. This identifier enables the resumption of a prior search and retrieval of additional results based on the same search criteria. If you want to start a new search with an updated | eyJsYXN0X3NvcnQiOlsxNzg3MDMxNzQ0MDAwXSwibmV4dF9jdXJzb8IiOjEyfQ== | false |
Data structures
RequestFilters
Key | Type | Description | Example | Required |
ad_published_date_range | DateRange | The date range during which the ads were published. The "min" value should represent a date after October 1, 2022. | { | true |
country_code | string | The country where the ads were targeted. The default value is ALL. | FR | false |
ad_type | string | The type of the ad, there are 3 types : "VIDEO", "IMAGES" and "TEXT" | "VIDEO" | false |
ad_status | string | The status of the ad, there are 2 types : "ACTIVE" and "INACTIVE" | "ACTIVE" | false |
ad_reach | list<string> | The filter that tells the show_uv of the ad, support 4 intervals : "0-10K", "10K-100K", "100K+" and "all" | ["0-10K", "10K-100K", "100K+"] or ["all"] | false |
ages | list<string> | The filter that tells targeting ages of the ad, support 7 intervals : "13,17", "18,24", "25,34", "35,44", "45,54", "55,100" and "all" | ["13,17", "18,24", "25,34", "35,44", "45,54", "55,100"] or ["all"] | false |
gender | string | The filter that tells targeting gender of the ad, support 3 type : FEMALE, MALE, ALL | "FEMALE" or "ALL" | false |
DateRange
Key | Type | Description | Example | Required |
min | string | The first date of the range and this needs to be after October 1, 2022. | 20260701 | true |
max | string | The last date of the range. | 20260810 | true |
Request example
curl -L -X POST 'https://open.tiktokapis.com/v2/research/adlib/ad/query/?fields=ad.id,ad.first_shown_date,ad.last_shown_date,ad.videos,ad.image_urls' \
-H 'Authorization: Bearer clt.example12345Example12345Example' \
-H 'Content-Type: application/json' \
--data-raw '{
"filters":{
"ad_type":"VIDEO",
"ad_status":"ACTIVE",
"ad_reach":["0-10K", "10K-100K", "100K+"],
"ages": ["13,17", "18,24", "25,34", "35,44", "45,54", "55,100"],
"gender":"FEMALE",
"country_code": "FR",
"ad_published_date_range": {
"min": "20260701",
"max": "20260810"
}
}
}'Response
Key | Type | Example |
data | QueryAdData | See the response example below. |
error | ErrorStructV2 | See the response example below. |
Response example
{
"data": {
"ads": [
{
"ad": {
"first_shown_date": 20210101,
"id": 1923845247192304,
"image_urls": [
"https://asdfcdn.com/17392712.jpeg?x-expires=1679169600\u0026x-signature=asdf"
],
"last_shown_date": 20210101,
"status": "active",
"videos": [
{"url": "https://asdfcdn.com/..../127364jmdfjsa93d8cn30dm2di/?mime_type=video_mp4"},
{"url": "https://asdfcdn.com/..../1kmeidhfb38u21nd82hsk389fd/?mime_type=video_mp4"}
],
"reach": {
"unique_user_seen": "11K"
}
},
"advertiser": {
"buisness_id": 3847236290405,
"business_name": "Awe Food Co.",
"paid_by": "Awe Co."
}
}
],
"has_more": "true",
"search_id": "2837438294054038"
},
"error": {
"code": "ok",
"http_status_code": 200,
"log_id": "202304280326050102231031430C7E754E",
"message": ""
}
}Data structures
QueryAdData
Key | Type | Description | Example |
ads | list<AdDto> | The list of ads that match all the criteria. | |
has_more | bool | The flag that indicates if there are more items to be returned. | true |
search_id | string | A unique identifier assigned to a cached search result. This identifier enables the resumption of a prior search and retrieval of additional results based on the same search criteria. | 2837438294054038 |
AdDto
Key | Type | Description | Example |
ad | Ad | The metadata of this ad. | |
advertiser | Advertiser | The metadata of the advertiser. |
Ad
Key | Type | Description | Example |
id | i64 | The ad ID. | 1923845247192304 |
first_shown_date | string | The first day when this ad was shown. | 20210101 |
last_shown_date | string | The last day when this ad was shown. | 20210101 |
status | string | The audit status of this ad: active or inactive. | active |
videos | list<AdVideo> | The list of videos. | |
image_urls | list<string> | The image URL list of this ad. | [ |
reach | Reach | The number of users who have seen this ad. | { |
AdVideo
Key | Type | Description | Example |
url | string | The video url of this ad | https://asdfcdn.com/..../127364jmdfjsa93d8cn30dm2di/?mime_type=video_mp4 |
Reach
Key | Type | Description | Example |
unique_users_seen | string | The number of users who have seen this ad. | "11K" |
Advertiser
Key | Type | Description | Example |
business_id | i64 | The advertiser's business ID. | 1755645247067185 |
business_name | string | The advertiser's business name. | Awe Food Co. |
paid_by | string | The advertiser's funding source. | Awe Co. |
ErrorStructV2
Key | Type | Description | Example |
code | string | The error category in string. | ok |
message | string | The detailed error description. | |
log_id | string | The unique ID associated with every request for debugging purporse. | 202207280326050102231031430C7E754E |
http_status_code | i32 | The http status code. | 200 |
