Ad¶

An ad is a single creative delivered inside an ad group. Nova Play ad groups contain 3 to 5 ads each; an advertiser account has roughly 20–35 ads in total. Ads are the finest level available in Reporting (data_level=AUCTION_AD).

Ad names follow {FORMAT}_{CONCEPT}_v{VERSION}:

Segment	Values
`FORMAT`	`VID` (video), `PLAY` (playable), `IMG` (static image)
`CONCEPT`	`Gameplay15s`, `Gameplay30s`, `Tutorial`, `BossFight`, `FailCompilation`, `Satisfying`, `Meme`, `StoryIntro`, `UpgradeLoop`, `Challenge`
`VERSION`	`v1`, `v2`, ... — a running number; a higher version is a later iteration of the same concept

Example: VID_Tutorial_v1, PLAY_Meme_v2, IMG_Gameplay15s_v4.

Get ads¶

GET /open_api/v1.3/ad/get/

Parameters¶

Name	Type	Required	Description
`advertiser_id`	string	Yes	Advertiser account id.
`filtering`	JSON object	No	Filter conditions, see below.
`fields`	JSON array of strings	No	Response fields to return. Defaults to all fields.
`page`	integer	No	Page number, starting at `1`. Default `1`.
`page_size`	integer	No	Rows per page, `1`–`1000`. Default `10`.

Filtering¶

filtering is a JSON object. Supported keys:

Key	Type	Description
`ad_ids`	array of strings	Return only these ad ids.
`adgroup_ids`	array of strings	Return ads in these ad groups.
`campaign_ids`	array of strings	Return ads in these campaigns.
`secondary_status`	string	One of the status values listed below.

Request¶

curl -s -G "https://business-api.huydata.com/open_api/v1.3/ad/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode "advertiser_id=7643153585721644371" \
  --data-urlencode 'filtering={"adgroup_ids":["1868805261510613175"]}' \
  --data-urlencode "page_size=2"

Response¶

{
  "code": 0,
  "message": "OK",
  "request_id": "64f9d9f657af4ab492fb",
  "data": {
    "list": [
      {
        "ad_id": "1831381570943309792",
        "ad_name": "VID_Tutorial_v1",
        "adgroup_id": "1868805261510613175",
        "adgroup_name": "EA_Broad_JP-KR-TW",
        "campaign_id": "1871286220402645533",
        "campaign_name": "DMS_TT_AND_EA_INSTALL_202602",
        "advertiser_id": "7643153585721644371",
        "ad_format": "SINGLE_VIDEO",
        "ad_text": "Play Dragon Merge Saga now!",
        "call_to_action": "DOWNLOAD_NOW",
        "landing_page_url": "https://play.google.com/store/apps/details?id=com.novaplay.dragonmerge",
        "operation_status": "ENABLE",
        "secondary_status": "AD_STATUS_DELIVERY_OK",
        "create_time": "2026-02-28 08:00:00",
        "modify_time": "2026-02-28 08:00:00",
        "video_id": "v10033g1870747822710067443"
      },
      {
        "ad_id": "1852349307584252475",
        "ad_name": "VID_Tutorial_v2",
        "adgroup_id": "1868805261510613175",
        "adgroup_name": "EA_Broad_JP-KR-TW",
        "campaign_id": "1871286220402645533",
        "campaign_name": "DMS_TT_AND_EA_INSTALL_202602",
        "advertiser_id": "7643153585721644371",
        "ad_format": "SINGLE_VIDEO",
        "ad_text": "Play Dragon Merge Saga now!",
        "call_to_action": "DOWNLOAD_NOW",
        "landing_page_url": "https://play.google.com/store/apps/details?id=com.novaplay.dragonmerge",
        "operation_status": "ENABLE",
        "secondary_status": "AD_STATUS_DELIVERY_OK",
        "create_time": "2026-04-10 08:00:00",
        "modify_time": "2026-04-10 08:00:00",
        "video_id": "v10033g1829917346747895997"
      }
    ],
    "page_info": {"page": 1, "page_size": 2, "total_number": 5, "total_page": 3}
  }
}

Field	Type	Description
`ad_id`	string	Numeric ad id. This is the `ad_id` dimension in Reporting.
`ad_name`	string	`{FORMAT}_{CONCEPT}_v{VERSION}`.
`adgroup_id`, `adgroup_name`	string	Parent ad group.
`campaign_id`, `campaign_name`	string	Parent campaign.
`advertiser_id`	string	Owning account.
`ad_format`	string	`SINGLE_VIDEO` or `SINGLE_IMAGE`. Playable ads are reported as `SINGLE_VIDEO` with an additional `playable_url`.
`ad_text`	string	Primary text.
`call_to_action`	string	`DOWNLOAD_NOW`.
`landing_page_url`	string	Store URL.
`operation_status`	string	`ENABLE` or `DISABLE`.
`secondary_status`	string	See table below.
`create_time`	string	`YYYY-MM-DD HH:MM:SS` UTC. The ad's first delivery day is the date part of `create_time`.
`modify_time`	string	`YYYY-MM-DD HH:MM:SS` UTC. For a switched-off ad it is the day of the last delivery.
`video_id`	string	Present for `SINGLE_VIDEO` ads (video and playable).
`image_ids`	array of strings	Present for `SINGLE_IMAGE` ads.
`playable_url`	string	Present only for playable ads (`PLAY_*`).

Image and playable examples (other fields omitted):

{
  "ad_id": "1842244998513681235",
  "ad_name": "IMG_Gameplay15s_v4",
  "ad_format": "SINGLE_IMAGE",
  "image_ids": ["v02011801390871976797680"],
  ...
}

{
  "ad_id": "1808121195245644392",
  "ad_name": "PLAY_Meme_v2",
  "ad_format": "SINGLE_VIDEO",
  "video_id": "v10033g1826428333808923411",
  "playable_url": "https://cdn.sandbox.invalid/playable/1826428333808923411/index.html",
  ...
}

Status values¶

`operation_status`	`secondary_status`	Meaning
`ENABLE`	`AD_STATUS_DELIVERY_OK`	Delivering.
`DISABLE`	`AD_STATUS_DISABLE`	The ad was switched off (creative retired). About a quarter of ads are retired 2–6 weeks after launch.
`ENABLE` / `DISABLE`	`AD_STATUS_CAMPAIGN_DISABLE`	The parent campaign is paused.
`ENABLE` / `DISABLE`	`AD_STATUS_CAMPAIGN_TIME_DONE`	The parent campaign's end date has passed. `operation_status` keeps the ad's own on/off state.

As with campaigns, the status describes today. An ad that is AD_STATUS_DISABLE today has rows in Reporting for the days it was running, and ads that were created after the date you query simply have no rows.

Example: retired ads in one campaign¶

curl -s -G "https://business-api.huydata.com/open_api/v1.3/ad/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode "advertiser_id=7990946724050865085" \
  --data-urlencode 'filtering={"campaign_ids":["1886693032310077738"],"secondary_status":"AD_STATUS_CAMPAIGN_TIME_DONE"}' \
  --data-urlencode 'fields=["ad_id","ad_name","operation_status","secondary_status"]' \
  --data-urlencode "page_size=2"

{
  "code": 0,
  "message": "OK",
  "request_id": "a549019ac9c947e59481",
  "data": {
    "list": [
      {"ad_id": "1834488558929037338", "ad_name": "PLAY_Challenge_v2", "operation_status": "ENABLE", "secondary_status": "AD_STATUS_CAMPAIGN_TIME_DONE"},
      {"ad_id": "1873279525904152886", "ad_name": "VID_Meme_v3", "operation_status": "ENABLE", "secondary_status": "AD_STATUS_CAMPAIGN_TIME_DONE"}
    ],
    "page_info": {"page": 1, "page_size": 2, "total_number": 6, "total_page": 3}
  }
}

Paging¶

With page_size=1000 every account's ads fit in one page. The ad list is the natural "dimension table" for ad-level reports: Reporting returns ad_id and, if you ask for them, ad_name, adgroup_name and campaign_name, but not the creative format or status.