Skip to main content
TikTok for DevelopersTikTok for Developers

Docs

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
  • ad.status
  • ad.status_statement
  • ad.videos
  • ad.image_urls
  • ad.reach
  • advertiser.business_id
  • advertiser.business_name
  • advertiser.paid_for_by

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.

If you provide "search_term", the "advertiser_business_ids" filter will be ignored

mobile games

false

search_type

string

The search type (which is case insensitive):

  • "exact_phrase": Returns results that contain an exact match for the search term. The default search type.
  • "fuzzy_phrase": Returns results that contain any or all of the words in the search term in any order.

fuzzy_phrase


false

max_count

i64

The maximum number of results returned at once. The default value is 10 and the maximum value is 50.

20

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 updatedsearch_term or filters value in the request, remove the search_id to avoid getting unexpected results.

20230501124205358FF99E4D6D1294A2A7


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.

{

"min": 20230102,

"max": 20230109

}

true

country_code

string

The country where the ads were targeted. The default value is ALL.

Supported Countries

FR


false

advertiser_business_ids

list<i64>

The advertiser's business ID of the ads.

If you provide "search_term", this filter will be ignored.

[294854736284058, 495736284058473]


false

unique_users_seen_size_range

SizeRange

The range of the number of users who've seen the content of this ad.


{

"min": "10K",

"max": "20K"

}

false

DateRange

Key

Type

Description

Example


Required

min

string

The first date of the range and this needs to be after October 1, 2022.

20230102

true

max

string

The last date of the range.

20230109

true

SizeRange

Key

Type

Description

Example

Required

min

string

The minimum size in thousands (K), millions (M), or billions (B).

The number before "K", "M", and "B" must be an integer less than 1000.

Valid: 0K, 120K, 2M, 1B

Invalid: 2000K, 1.1M, 1B2M


false

max

string

The maximum size in thousands (K), millions (M), or billions (B)

The number before "K", "M", and "B" must be an integer less than 1000.

The value must be greater than 0.

Valid: 120K, 2M, 1B

Invalid: 0K, 2000K, 1.1M, 1B2M


false

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' \
-H 'Authorization: Bearer clt.example12345Example12345Example' \
-H 'Content-Type: application/json' \
--data-raw '{
   "filters":{
       "advertiser_business_ids": [3847236290405, 319282903829],
       "ad_published_date_range": {
            "min": "20210102",
            "max": "20210109"
       },
       "country_code": "FR",
       "unique_users_seen_size_range": {
           "min": "10K",
           "max": "1M"
       },
   },
   "search_term": "mobile games"
}'

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.

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.


[

"https://asdfcdn.com/17392712.jpeg?x-expires=1679169600\u0026x-signature=asdf"

]

reach

Reach


The number of users who have seen this ad.


{

"unique_users_seen": "11K"

}

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