Ad Group¶

An ad group sits under a campaign and holds the targeting: which countries (location_ids), which operating system, which audience, and what the delivery is optimized for. Every Nova Play campaign has 2 or 3 ad groups, one per audience type (Broad, Lookalike_Payers, Interest_Gaming), each targeting a subset of the campaign's geographic group.

Ad group names follow {GEO}_{AUDIENCE}_{COUNTRIES} where countries are ISO codes joined by -, for example EA_Broad_JP-KR-TW or T1_Lookalike_Payers_AU-CA-DE-GB-US.

Get ad groups¶

GET /open_api/v1.3/adgroup/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
`adgroup_ids`	array of strings	Return only these ad group ids.
`campaign_ids`	array of strings	Return ad groups belonging to 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/adgroup/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode "advertiser_id=7643153585721644371" \
  --data-urlencode 'filtering={"campaign_ids":["1871286220402645533"]}' \
  --data-urlencode "page_size=2"

Response¶

{
  "code": 0,
  "message": "OK",
  "request_id": "ed421acd17f54838bdaf",
  "data": {
    "list": [
      {
        "adgroup_id": "1868805261510613175",
        "adgroup_name": "EA_Broad_JP-KR-TW",
        "campaign_id": "1871286220402645533",
        "campaign_name": "DMS_TT_AND_EA_INSTALL_202602",
        "advertiser_id": "7643153585721644371",
        "app_id": "7642218708447580001",
        "app_download_url": "https://play.google.com/store/apps/details?id=com.novaplay.dragonmerge",
        "app_type": "APP_ANDROID",
        "placement_type": "PLACEMENT_TYPE_AUTOMATIC",
        "placements": ["PLACEMENT_TIKTOK", "PLACEMENT_PANGLE"],
        "location_ids": ["1861060", "1835841", "1668284"],
        "age_groups": ["AGE_18_24", "AGE_25_34", "AGE_35_44", "AGE_45_54", "AGE_55_100"],
        "gender": "GENDER_UNLIMITED",
        "operating_systems": ["ANDROID"],
        "audience_type": "BROAD",
        "optimization_goal": "INSTALL",
        "optimization_event": "INSTALL",
        "billing_event": "OCPM",
        "bid_type": "BID_TYPE_NO_BID",
        "budget_mode": "BUDGET_MODE_INFINITE",
        "budget": 0.0,
        "schedule_type": "SCHEDULE_FROM_NOW",
        "schedule_start_time": "2026-02-28 00:00:00",
        "schedule_end_time": null,
        "operation_status": "ENABLE",
        "secondary_status": "ADGROUP_STATUS_DELIVERY_OK",
        "create_time": "2026-02-27 10:00:00",
        "modify_time": "2026-02-27 10:00:00"
      },
      {
        "adgroup_id": "1822048926325183510",
        "adgroup_name": "EA_Lookalike_Payers_JP-KR-TW",
        "campaign_id": "1871286220402645533",
        "campaign_name": "DMS_TT_AND_EA_INSTALL_202602",
        "advertiser_id": "7643153585721644371",
        "app_id": "7642218708447580001",
        "app_download_url": "https://play.google.com/store/apps/details?id=com.novaplay.dragonmerge",
        "app_type": "APP_ANDROID",
        "placement_type": "PLACEMENT_TYPE_AUTOMATIC",
        "placements": ["PLACEMENT_TIKTOK", "PLACEMENT_PANGLE"],
        "location_ids": ["1861060", "1835841", "1668284"],
        "age_groups": ["AGE_18_24", "AGE_25_34", "AGE_35_44", "AGE_45_54", "AGE_55_100"],
        "gender": "GENDER_UNLIMITED",
        "operating_systems": ["ANDROID"],
        "audience_type": "LOOKALIKE",
        "optimization_goal": "INSTALL",
        "optimization_event": "INSTALL",
        "billing_event": "OCPM",
        "bid_type": "BID_TYPE_NO_BID",
        "budget_mode": "BUDGET_MODE_INFINITE",
        "budget": 0.0,
        "schedule_type": "SCHEDULE_FROM_NOW",
        "schedule_start_time": "2026-02-28 00:00:00",
        "schedule_end_time": null,
        "operation_status": "ENABLE",
        "secondary_status": "ADGROUP_STATUS_DELIVERY_OK",
        "create_time": "2026-02-27 06:00:00",
        "modify_time": "2026-02-27 06:00:00"
      }
    ],
    "page_info": {"page": 1, "page_size": 2, "total_number": 3, "total_page": 2}
  }
}

Field	Type	Description
`adgroup_id`	string	Numeric ad group id.
`adgroup_name`	string	`{GEO}_{AUDIENCE}_{COUNTRIES}`.
`campaign_id`, `campaign_name`	string	Parent campaign.
`advertiser_id`	string	Owning account.
`app_id`	string	Numeric TikTok app id of the promoted game. It is not the store package. Resolve it with `/app/list/`.
`app_download_url`	string	Store URL of the game.
`app_type`	string	`APP_ANDROID` or `APP_IOS`.
`placement_type`	string	`PLACEMENT_TYPE_AUTOMATIC`.
`placements`	array of strings	`PLACEMENT_TIKTOK`, `PLACEMENT_PANGLE`.
`location_ids`	array of strings	Numeric TikTok region ids of the targeted countries. Resolve them with `/tool/region/get/`. In the example `1861060` = Japan, `1835841` = South Korea, `1668284` = Taiwan.
`age_groups`	array of strings	Targeted age brackets (always all adult brackets).
`gender`	string	`GENDER_UNLIMITED`.
`operating_systems`	array of strings	`["ANDROID"]` or `["IOS"]`.
`audience_type`	string	`BROAD`, `LOOKALIKE` (lookalike of payers) or `INTEREST` (gaming interest).
`optimization_goal`	string	`INSTALL` for `_INSTALL_` campaigns, `VALUE` for `_VALUE_` campaigns.
`optimization_event`	string	`INSTALL` or `IN_APP_EVENT` (purchase) respectively.
`billing_event`	string	`OCPM`.
`bid_type`	string	`BID_TYPE_NO_BID` (lowest cost).
`budget_mode`	string	`BUDGET_MODE_INFINITE`: the ad group has no budget of its own, the campaign's daily budget applies.
`budget`	number	Always `0.0` (see `budget_mode`).
`schedule_type`	string	`SCHEDULE_FROM_NOW` (open-ended) or `SCHEDULE_START_END`.
`schedule_start_time`	string	`YYYY-MM-DD 00:00:00`, first delivery day of the campaign.
`schedule_end_time`	string or null	`YYYY-MM-DD 00:00:00` exclusive end (the day after the last delivery day), or `null` when open-ended.
`operation_status`	string	`ENABLE` or `DISABLE`.
`secondary_status`	string	See table below.
`create_time`, `modify_time`	string	`YYYY-MM-DD HH:MM:SS` UTC.

Status values¶

`secondary_status`	Meaning
`ADGROUP_STATUS_DELIVERY_OK`	Delivering.
`ADGROUP_STATUS_CAMPAIGN_DISABLE`	The parent campaign is paused. `operation_status` is `DISABLE`.
`ADGROUP_STATUS_TIME_DONE`	The scheduled end date has passed.

Ad groups inherit their status from the campaign; there is no ad-group-level pause in these accounts.

Example: a VALUE campaign's ad groups¶

curl -s -G "https://business-api.huydata.com/open_api/v1.3/adgroup/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode "advertiser_id=7548458757843580535" \
  --data-urlencode 'filtering={"campaign_ids":["1841952719001468267"]}' \
  --data-urlencode 'fields=["adgroup_id","adgroup_name","optimization_goal","optimization_event","secondary_status"]'

{
  "code": 0,
  "message": "OK",
  "request_id": "eb2b69134a364815887b",
  "data": {
    "list": [
      {"adgroup_id": "1820220696054051059", "adgroup_name": "T1_Broad_AU-CA-DE-US", "optimization_goal": "VALUE", "optimization_event": "IN_APP_EVENT", "secondary_status": "ADGROUP_STATUS_DELIVERY_OK"},
      {"adgroup_id": "1862937878652036735", "adgroup_name": "T1_Lookalike_Payers_AU-CA-DE-GB-US", "optimization_goal": "VALUE", "optimization_event": "IN_APP_EVENT", "secondary_status": "ADGROUP_STATUS_DELIVERY_OK"},
      {"adgroup_id": "1818699474479489474", "adgroup_name": "T1_Interest_Gaming_CA-DE", "optimization_goal": "VALUE", "optimization_event": "IN_APP_EVENT", "secondary_status": "ADGROUP_STATUS_DELIVERY_OK"}
    ],
    "page_info": {"page": 1, "page_size": 10, "total_number": 3, "total_page": 1}
  }
}

Paging¶

An account has between 5 and 10 ad groups, so page_size=100 returns all of them in one call. If you keep the default page_size=10, read page_info.total_page and request the remaining pages.