VI | EN
Message us on Messenger
Developer resources

Estimate audience size — TikTok Business API

Estimate audience size · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

Estimate audience size

POST/ad/audience_size/estimate/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/
Description

Use this endpoint to get the estimated audience size. The parameters for this endpoint are similar to the ones for creating an ad group.

> Note

Due to data security requirements, an estimated audience size does not include audiences under 18 years of age. Ad delivery as permitted by applicable laws will not be affected.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/

Authentication & shop

NameInTypeSampleDescription
AuthorizationheaderheaderBearer q360_live_ab12cd34_…Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_idquerystring7000000000000000001Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Request parameters

NameInTypeRequiredSampleDescription
placement_typebodystringNoPlacement type. Enum values: - PLACEMENT_TYPE_AUTOMATIC (Automatic placement) - PLACEMENT_TYPE_NORMAL (Select placement). Default value: PLACEMENT_TYPE_NORMAL.
placementsbodystring[]NoThe apps where you want to deliver your ads. Required when placement_type is PLACEMENT_TYPE_NORMAL, and ignored when placement_type is PLACEMENT_TYPE_AUTOMATIC. Currently, we support PLACEMENT_TIKTOK, PLACEMENT_PANGLE and PLACEMENT_GLOBAL_APP_BUNDLE. For a full list of enum values, see Enumeration - Placement. Note: - The available locations you can target with the Global App Bundle placement (PLACEMENT_GLOBAL_APP_BUNDLE) are: Brazil, Indonesia, Vietnam, the Philippines, Thailand, Malaysia, Mexico, Saudi Arabia, and Japan. - The Global App Bundle placement (PLACEMENT_GLOBAL_APP_BUNDLE) does not support the optimization goal Landing Page View (optimization_goal=TRAFFIC_LANDING_PAGE_VIEW). To learn about the optimization goal, refer to the section Enumerations-Optimization goal. - For Product Sales campaigns (objective_type = PRODUCT_SALES), only TikTok placement (PLACEMENT_TIKTOK) is supported.
pixel_idbodystringNoPixel ID. Only application for landing pages. It needs to be passed in with the external_action field. Use /pixel/list/ endpoint to get all Pixel IDs.
ios14_targetingbodystringNoThe iOS devices that you want to target. Note: When campaign_type of the campaign is set as IOS14_CAMPAIGN, ios14_targeting is required and must be specified as IOS14_PLUS. Enum values: - UNSET: The default value for ad groups that were created before the introduction of this field. - IOS14_MINUS: Devices with iOS 14.4 or earlier versions, which are not affected by the iOS 14 privacy update. This is the default value for ad groups that are created after the introduction of this field. - IOS14_PLUS: Devices with iOS 14.5 and above. The iOS 14 privacy update has been enforced in this group of devices. Specify this value if you want to create an iOS 14 campaign. Each iOS 14 campaign can have up to 2 active ad groups. If IOS14_PLUS is specified, this field cannot be updated. If IOS14_PLUS is specified for this field, the system will verify if related fields meet the requirements for an iOS 14 campaign. The following fields will be checked. - app_id: It must not be an ID of an Android app. - operating_systems: It must not be ANDROID or PC. - min_ios_version: You must specify a value for this field, and the the value must not contradict with the selection for ios14_targeting. - min_android_version: Must not be specified. - optimization_goal: Can only be set to CLICK, INSTALL, IN_APP_EVENT or VALUE. - shopping_ads_retargeting_type: Must not be specified. - shopping_ads_retargeting_actions_days: Must not be specified. - conversion_window: Must not be specified. - On the Ad level, deeplink_type must not be set to DEFERRED_DEEPLINK.
objective_typebodystringYesYour objective type. For enum values, see Enumeration - Advertising Objective.
optimization_goalbodystringYesOptimization goal. For enum values, see Enumeration - Optimization Goal.
promotion_typebodystringNoRequired when objective_type = PRODUCT_SALES. Promotion type and you can decide where you'd like to promote your products using this field. For enum values, see Enumeration - Promotion Type.
product_sourcebodystringNoRequired when objective_type = PRODUCT_SALES. Product source where you want to get products for promotion. Enum values: UNSET, CATALOG (Catalog), STORE (TikTok Shop).
catalog_idbodystringNoRequired when objective_type=PRODUCT_SALES. Catalog ID.
product_set_idbodystringNoProductSet ID of the catalog. 0 means selecting all product sets. The default value is 0.
catalog_authorized_bc_idbodystringNoFor catalogs in Business Center, you must specify the ID of the Business Center that a catalog belongs to.
shopping_ads_retargeting_typebodystringNoValid when the campaign objective_type is PRODUCT_SALES. The retargeting type of shopping ads. Enum values: - LAB1: Retargeting audiences who viewed products or added products to cart but didn't purchase products. - LAB2: Retargeting audiences who added products to cart but didn't purchase products. - LAB3: Retargeting audiences using custom combination. - OFF: No retargeting.
shopping_ads_retargeting_actions_daysbodynumberNoRequired when shopping_ads_retargeting_type is LAB1 or LAB2. The valid time range for the specified audience action. Audiences who have completed the specified action within the time range will be retargeted by the shopping ads. Value range: 1, 2, 3, 7, 14, 30, 60, 90, 180.
included_custom_actionsbodyobject[]NoWhen shopping_ads_retargeting_type is LAB3, you need to pass in either included_custom_actions or excluded_custom_actions. The custom action that you want to use as "Include" conditions for filtering out the shopping ads audiences to be retargeted.
excluded_custom_actionsbodyobject[]NoWhen shopping_ads_retargeting_type is LAB3, you need to pass in either included_custom_actions or excluded_custom_actions. The custom action that you want to use as "Exclude" conditions for filtering out the shopping ads audiences to be retargeted.
audience_idsbodystring[]NoList of audience IDs. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint.
excluded_audience_idsbodystring[]NoA list of audience ID to be excluded. You can get audience IDs by using the /dmp/custom_audience/list/ endpoint.
audience_rulebodyobjectNoAudience rule, valid if objective_type is TRAFFIC or WEB_CONVERSIONS. For details, see Audience Rules
audience_typebodystringNoApp retargeting audience type. For enum values, see Enumeration - App Retargeting Audience Type
location_idsbodystring[]NoIDs of the locations that you want to target. You need to set location_ids or zipcode_ids or both. Max size: 3,000. If you provide both location_ids and zipcode_ids, the combined total of location IDs, zip code IDs, and postal code IDs cannot exceed 3,000 per ad group. To get the available locations and corresponding IDs based on your placement and objective, use the /tool/region/ or /tool/targeting/search/ endpoint. For enum values, see Location IDs. Note: - Overlapping targeted locations are not supported. For instance, you cannot target the U.S. and the state of California at the same time.
zipcode_idsbodystring[]NoZip code IDs or postal code IDs that you want to use to target locations. You need to set location_ids or zipcode_ids or both. Max size: 3,000. If you provide both location_ids and zipcode_ids, the combined total of location IDs, zip code IDs, and postal code IDs cannot exceed 3,000 per ad group. You can get the available zip code IDs or postal code IDs based on your placement, objective and keyword via geo_id (when geo_type = ZIP_CODE) returned from the /tool/targeting/search/ endpoint. Note: - Zip code targeting is currently only supported for the US and postal code targeting is currently only supported for Canada, Brazil, Indonesia, Thailand, and Vietnam. - Targeting postal code areas in Brazil, Indonesia, Thailand, and Vietnam is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative. - You can only use zip code targeting or postal code targeting on TikTok placement. Therefore, the placements value needs to include PLACEMENT_TIKTOK. - Overlapping targeted locations are not supported. For instance, you cannot target the U.S. and the state of California at the same time. - To get information about zip code IDs or postal code IDs, you can only use /tool/targeting/info/.
isp_idsbodystring[]NoIDs of the Internet service providers (ISP) that you want to target. Valid only when you specify a valid location ID at the country or region level via location_ids at the same time. You can use /tool/targeting/list/ to get the ISP IDs that you can target for a location ID. Note: When you pass in isp_ids, you cannot set the placement as Global App Bundle only (placements =PLACEMENT_GLOBAL_APP_BUNDLE).
genderbodystringNoGender that you want to target. Enum: GENDER_FEMALE,GENDER_MALE,GENDER_UNLIMITED
age_groupsbodystring[]NoAge groups you want to target. For enum values, see Enumeration - Targeting Age Group.
languagesbodystring[]NoCodes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code. You can get language codes via /tool/language/, and if you don't want to limit the languages you target, assign an empty value to this field or do not pass in this field.
interest_category_idsbodystring[]NoIDs of general interest categories that you want to use to target audiences. - To search for or list general interest category IDs, use /targeting/search/ (recommended) or /tool/interest_category/. - To get recommended interest category IDs based on your industry, use /tool/targeting_category/recommend/.
interest_keyword_idsbodystring[]NoIDs of additional interest categories that you want to use to target audience. To search for additional interest categories, use /targeting/search/ (recommended) or /tool/interest_keyword/recommend/.
purchase_intention_keyword_idsbodystring[]NoIDs of purchase intention categories that you want to use to target audiences with an interest in purchases related to a content category. To search for or list purchase intention category IDs, use /targeting/search/. Note: - Do not pass in purchase_intention_keyword_ids and interest_keyword_ids at the same time. Otherwise, keyword conflict will occur. - purchase_intention_keyword_ids only supports Auction ads with theobjective_type as APP_PROMOTION,WEB_CONVERSIONS,LEAD_GENERATION, TRAFFIC, or PRODUCT_SALES with product_source as CATALOG, and the placement setting should include TikTok (PLACEMENT_TIKTOK) or Pangle (PLACEMENT_PANGLE).
actionsbodyobject[]NoA list of targeting behavioral category objects.
operating_systemsbodystring[]NoDevice operating systems that you want to target. Only one value is allowed. Enum values: ANDROID, IOS. This field is required in two scenarios: - objective_type is APP_PROMOTION - objective_type is TRAFFIC and promotion_type is APP_IOS or APP_ANDROID
min_ios_versionbodystringNoMinimum iOS version. For enum values, see Enumeration - Minimum iOS Version.
min_android_versionbodystringNoMinimum device Android version. For enum values, see Enumeration - Minimum Android Version.
device_model_idsbodystring[]NoIDs of the device models that you want to target. Use /tool/device_model/ to get the complete list of device model IDs and their statuses, and only active devices (is_active = True in the response of /tool/device_model/) can be used to create ads. Note: Device model (device_model_ids) and device price (device_price_ranges) cannot be set at the same time.
network_typesbodystring[]NoDevice connection types that you want to target. Default: unlimited. For enum values, see Enumeration - Connection Type.
household_incomebodystring[]NoHousehold income that you want to target. Enum values: TOP5(Top 5% of ZIP codes), TOP10(Top 10% of ZIP codes), TOP10_25(Top 10% -25% of ZIP codes), TOP25_50(Top 25% - 50% of ZIP codes). Note: - It only supports the ad objectives for Auction ads. See Advertising objectives for details. - It is only applicable to the TikTok Placement in the US. - If you have specified special_industries at the campaign level, then you cannot use the field here.
spending_powerbodystringNoSpending power that you want to target. Enum values: ALL, HIGH. If it is set to HIGH, you can target high spending users who typically spend more on purchases on TikTok ads than average users. Note: : - This field does not support the advertising objectives PRODUCT_SALES and RF_REACH at the campaign level. See Advertising objectives for details. - This field supports Automatic Placement and Select Placement with TikTok included. Therefore, you need to set placement_type to PLACEMENT_TYPE_AUTOMATIC, or include PLACEMENT_TIKTOK in the value of placements. Note that if you specify Pangle as a placement, the spending power targeting won't take effect on Pangle. - It cannot be used with special industries targeting at the same time. If you have specified special_industries at the campaign level, then you cannot use the field here. - When auto_targeting_enabled is true at the ad group level, then spending_power will be automatically set to ALL.
device_price_rangesbodynumber[]NoTargeting device price range. 10000 means 1000+. The numbers must be in multiples of 50. Important: The upper limit you set will be added by 50 and the resulting new number will be used as the actual upper limit for device targeting. The actual upper limit is shown in the ad group settings in TikTok Ads Manager. If you set and get the price range of [0, 250], it actually means [0, 300].
carrier_idsbodystring[]NoCarriers that you want to target. A carrier is valid only when the in_use field for the carrier is true. The carriers must be consistent with the location(s) that you want to target. Use /tool/carrier/ endpoint to get the enum values.
included_pangle_audience_package_idsbodystring[]NoIDs of the Pangle audiences that you want to include. Valid only for Pangle placement. You can get audience IDs (package_id) by using the /pangle_audience_package/get/ endpoint. You need to set bind_type to INCLUDE. Do not specify this field and excluded_pangle_audience_package_ids at the same time.
excluded_pangle_audience_package_idsbodystring[]NoIDs of the Pangle audiences that you want to exclude. Valid only for Pangle placement. You can get audience IDs (package_id) by using the /pangle_audience_package/get/ endpoint. You need to set bind_type to EXCLUDE. Do not specify this field and included_pangle_audience_package_ids at the same time.
blocked_pangle_app_idsbodystring[]NoPangle app block list ID. You can get an ID via the app_package_id field returned by Get Pangle block list. It only takes effect when Pangle placement is selected.
targeting_expansionbodyobjectNoSettings about targeting expansion
auto_targeting_enabledbodybooleanNoWhether to enable automated targeting. Enum values: True, False.
contextual_tag_idsbodystring[]NoContextual tag IDs. You can use /tool/contextual_tag/get/ to get available contextual tags. See Contextual targeting to learn more about how to use Contextual targeting. Note: - This is an allowlist-only feature. If you would like to access it, please contact your TikTok representative. - Only supports REACH and VIDEO_VIEWS as objectives (objective_type) at the campaign level. - Not supported when brand_safety_type is set to THIRD_PARTY.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective_type":"","optimization_goal":"","included_custom_actions":[{}],"excluded_custom_actions":[{}],"actions":[{}],"targeting_expansion":{}}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/",
    params={},
    json={
        "objective_type": "",
        "optimization_goal": "",
        "included_custom_actions": [
            {}
        ],
        "excluded_custom_actions": [
            {}
        ],
        "actions": [
            {}
        ],
        "targeting_expansion": {}
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())
Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"objective_type":"","optimization_goal":"","included_custom_actions":[{}],"excluded_custom_actions":[{}],"actions":[{}],"targeting_expansion":{}}),
});
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/ad/audience_size/estimate/' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"objective_type":"","optimization_goal":"","included_custom_actions":[{}],"excluded_custom_actions":[{}],"actions":[{}],"targeting_expansion":{}}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Business)

NameTypeSampleDescription
codenumberResponse code. For the complete list of response codes and descriptions, see Appendix - Return Codes.
messagestringResponse message. For details, see Appendix - Return Codes.
dataobjectReturn data
user_count_stagenumberEvaluation of the estimated audience size. Enum: - `1`: Too Narrow. The estimated audience size is less than 10,000, and accounts for less then 20% of possible audience size in the selected locations on the selected placements. - `2`: Narrow. The estimated audience size is equal to or larger than 10,000, but still accounts for less than 20% of possible audience size in the selected locations on the selected placements. - `3`: Balanced. The estimated audience size accounts for 20% or more but less than 80% of possible audience size in the selected locations on the selected placements. - `4`: Fairly Broad: The estimated audience size accounts for 80% or more of the possible audience size in the selected locations on the selected placements
user_countobjectEstimated audience sizes
lower_endnumberLower-end of the estimated audience size range
upper_endnumberUpper-end of the estimated audience size range
purchase_intention_keyword_idsstring[]IDs of purchase intention keywords that you want to use to target audiences with an interest in purchases related to a content category.
request_idstringThe log id of the request, which uniquely identifies a request

Response sample

HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "user_count": {
            "lower_end": 107229000,
            "upper_end": 131059000
        }
    },
    "request_id": "2021090909090909024510008412345678"
}
(/code);

Get started

  1. Sign up for Partner
  2. Enable a data type of the Ads (Marketing API) group on the platform page
  3. Create an API key (tick the TikTok Business channel)
  4. Call it as in the examples above