TikTok Ads is currently in beta. The info in this guide is subject to change.
This integration is powered by Singer's tiktok-ads tap and certified by Stitch. Check out and contribute to the repo on GitHub.
For support, contact Stitch support.
TikTok Ads integration summary
Stitch’s TikTok Ads integration replicates data using the TikTok Ads API (v1.2). Refer to the Schema section for a list of objects available for replication.
TikTok Ads feature snapshot
A high-level look at Stitch's TikTok Ads (v1) integration, including release status, useful links, and the features supported in Stitch.
STITCH | |||
Release status |
Beta |
Supported by | |
Stitch plan |
Standard |
API availability |
Available |
Singer GitHub repository | |||
REPLICATION SETTINGS | |||
Anchor Scheduling |
Supported |
Advanced Scheduling |
Supported |
Table-level reset |
Unsupported |
Configurable Replication Methods |
Unsupported |
DATA SELECTION | |||
Table selection |
Supported |
Column selection |
Supported |
Select all |
Supported |
||
TRANSPARENCY | |||
Extraction Logs |
Supported |
Loading Reports |
Supported |
Connecting TikTok Ads
TikTok Ads setup requirements
To set up TikTok Ads in Stitch, you need:
-
Access to a TikTok Ads account. This is necessary to login to the Ad Manager account.
-
Access to a TikTok Ads Ad Manager account. Verify that you have access to use the Ad accounts you want to replicate data from. This is necessary to connect to Stitch.
Step 1: Add TikTok Ads as a Stitch data source
- Sign into your Stitch account.
-
On the Stitch Dashboard page, click the Add Integration button.
-
Click the TikTok Ads icon.
-
Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.
For example, the name “Stitch TikTok Ads” would create a schema called
stitch_tiktok_ads
in the destination. Note: Schema names cannot be changed after you save the integration.
Step 2: Define the historical replication start date
The Sync Historical Data setting defines the starting date for your TikTok Ads integration. This means that data equal to or newer than this date will be replicated to your data warehouse.
Change this setting if you want to replicate data beyond TikTok Ads’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.
Step 3: Create a replication schedule
In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.
TikTok Ads integrations support the following replication scheduling methods:
-
Advanced Scheduling using Cron (Advanced or Premium plans only)
To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.
Step 4: Authorize Stitch
- Next, you’ll be prompted to log into your TikTok account and approve Stitch’s access to your TikTok Ads data. Note that we will only ever read your data.
- Click Sign in with TikTok to connect.
- Sign in with your TikTok account.
- After your credentials are validated, you’ll be directed back to Stitch and prompted to select the TikTok Ads accounts you want to for which you want to run extractions.
- When finished, click Check and Save, then click All Done.
Step 5: Set objects to replicate
The last step is to select the tables and columns you want to replicate. Learn about the available tables for this integration.
Note: If a replication job is currently in progress, new selections won’t be used until the next job starts.
For TikTok Ads integrations, you can select:
-
Individual tables and columns
-
All tables and columns
Click the tabs to view instructions for each selection method.
- In the integration’s Tables to Replicate tab, locate a table you want to replicate.
-
To track a table, click the checkbox next to the table’s name. A blue checkmark means the table is set to replicate.
-
To track a column, click the checkbox next to the column’s name. A blue checkmark means the column is set to replicate.
- Repeat this process for all the tables and columns you want to replicate.
- When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.
- Click into the integration from the Stitch Dashboard page.
-
Click the Tables to Replicate tab.
- In the list of tables, click the box next to the Table Names column.
-
In the menu that displays, click Track all Tables and Fields:
- Click the Finalize Your Selections button at the bottom of the page to save your data selections.
Initial and historical replication jobs
After you finish setting up TikTok Ads, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.
For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.
Initial replication jobs with Anchor Scheduling
If using Anchor Scheduling, an initial replication job may not kick off immediately. This depends on the selected Replication Frequency and Anchor Time. Refer to the Anchor Scheduling documentation for more information.
Free historical data loads
The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.
TikTok Ads table reference
Schemas and versioning
Schemas and naming conventions can change from version to version, so we recommend verifying your integration’s version before continuing.
The schema and info displayed below is for version 1 of this integration.
This is the latest version of the TikTok Ads integration.
Table and column names in your destination
Depending on your destination, table and column names may not appear as they are outlined below.
For example: Object names are lowercased in Redshift (CusTomERs
> customers
), while case is maintained in PostgreSQL destinations (CusTomERs
> CusTomERs
). Refer to the Loading Guide for your destination for more info.
adgroups
Replication Method : |
Key-based Incremental |
Replication Key |
modify_time |
Primary Key |
adgroup_name : advertiser_id : campaign_id : modify_time |
Official docs : |
action_v2
A list of action category objects.
|
||||||
adgroup_id
Ad group ID |
||||||
adgroup_name
Ad group Name |
||||||
advertiser_id
Advertiser ID |
||||||
age
Age groups you want to target. For enum values, see Enumeration - Age Group. |
||||||
android_osv
Minimum Android version. For enum values, see Enumeration - Minimum Android Version. |
||||||
app_download_url
App download link |
||||||
app_id
The Application ID of the promoted app. You can get app_id by using the /app/list/ endpoint. |
||||||
audience
A list of audience IDs |
||||||
audience_type
App retargeting audience type. For enum values, see Enumeration - App Retargeting Audience Type. |
||||||
bid
Bid price. The maximum cost per result you are willing to bid (for Bid Cap bidding strategy), or an average cost per result that you want to achieve (for Cost Cap bidding strategy). |
||||||
bid_type
Bidding strategy that determines how the system manages your cost per result, spends your budget, and how it delivers ads. See (Enumeration - Bidding Strategy](https://ads.tiktok.com/marketing_api/docs?id=1701890985340929]. |
||||||
billing_event
Bid method. See Enumeration - Bid method for optional values. |
||||||
brand_safety
Brand safety type. Enum values: 1. THIRD_PARTY: Use a third-party brand safety solution. You also need to pass in a value to the brand_safety_partner field. 2. LIMITED_INVENTORY: Use TikTok’s brand safety solution. Currently, the only supported safety level is Limited Inventory, which is a strict brand safety level. It would exclude all identifiable risky content. To get the countries and regions that your ads can be deployed to based on your brand safety settings, use the /tools/regions/ endpoint. |
||||||
brand_safety_partner
Brand safety partner. Available only when brand_safety is THIRD_PARTY. Enum values: IAS, OPEN_SLATE. To get the countries and regions that your ads can be deployed to based on your brand safety settings, use the /tools/regions/ endpoint. You need to pass in the brand safety type and brand safety partner. |
||||||
budget
Ad budget. Returns 0.0 when Campaign Budget Optimization (budget_optimize_switch) is on. |
||||||
budget_mode
Budget mode. If Campaign Budget Optimization is enabled, BUDGET_MODE_INFINITE will be returned. For more information about budget modes, see Budget Settings. |
||||||
buy_impression
Impressions to be purchased. Returned when objective_type of the related campaign is RF_REACH. |
||||||
buy_reach
Purchased user reach. Returned when objective_type of the related campaign is RF_REACH. |
||||||
campaign_id
Campaign ID |
||||||
carriers_v2
Carriers that you want to target. A carrier is valid only when the in_use field for the carrier is true. For enum values (carrier_v2_id), see Get carriers.
|
||||||
catalog_authorized_bc
For catalogs in Business Center, this field returns the ID of the Business Center that a catalog belongs to. |
||||||
catalog_id
Catalog ID。Return when the corresponding campaign objective_type is CATALOG_SALES. |
||||||
connection_type
Device connection types that you want to target. Default: unlimited. For enum values, see Enumeration - Connection Type.
|
||||||
conversion_bid
Where you can set a target cost per conversion for oCPM(Optimized Cost per Mille). |
||||||
conversion_window
The time frame when you would like a conversion to happen after a user clicks on or views your ad. Your ad delivery will be optimized using the conversion data during the time frame you select. This setting will not impact your attribution data. For enum values, see Enumeration - Conversion Window. |
||||||
cpv_video_duration
Optimized video playback duration. Optional values include: SIX_SECONDS (video playback 6 seconds) and TWO_SECONDS (video playback 2 seconds) |
||||||
create_time
Time at which the ad group was created. |
||||||
creative_material_mode
The strategy that your creatives will be delivered. Note: When you choose automated ad, your creative materials will automatically be combined for delivery. Tiktok Ads’ smart optimization algorithm is applied and will be used to achieve the best ad performance during delivery. Enum values: CUSTOM(custom), DYNAMIC(automated) |
||||||
daily_retention_ratio
Day 2 retention ratio. Formula: daily_retention_ratio = conversion_bid/deep_cpabid. Value range is (0,1]. Only valid when placement is PLACEMENT_PANGLE and deep_external_action is NEXT_DAY_OPEN. |
||||||
dayparting
Ad delivery arrangement, in the format of a string that consists of 48 x 7 characters. Each character is mapped to a 30-minute timeframe from Monday to Sunday. Each character can be set to either 0 or 1. 1 represents delivery in the 30-minute timeframe, and 0 stands for non-delivery in the 30-minute timeframe. The first character is mapped to 0:01-0:30 of Monday; The second character is mapped to 0:31-1:00 of Monday, and the last character represents 23:31-0:00 Sunday. Note : Not specified, all-0, or all-1 are considered as full-time delivery. |
||||||
deep_bid_type
Bidding strategy for in-app events. For enum values and their decriptions, see Enumeration - Deep-level Bidding Strategy. |
||||||
deep_cpabid
Specify bid price in this field after you’ve chosen a bidding strategy for in-app events, for example VO_MIN. |
||||||
deep_external_action
The secondary goal when optimization goal (optimize_goal) is Install (INSTALL) or Value (VALUE). For enum values, see Conversion events - Secondary-goal events. |
||||||
device_models
List of device model IDs. For more details about device models, see Enumeration-Device Models.
|
||||||
device_price
Targeting 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]. |
||||||
dpa_retargeting_type
The types of ad redirection in the catalog. Returned when the corresponding campaign objective_type is CATALOG_SALES. |
||||||
enable_inventory_filter
Inventory filtering (filtering security videos, hides unsafe videos), valid only for the PLACEMENT_TIKTOK placement. Optional values are: true to filter, false not to filter. |
||||||
excluded_audience
A list of excluded audience IDs.
|
||||||
external_action
Conversion event for the ad group. See Conversion events for more. |
||||||
external_type
Promotion type and you can decide where you’d like to promote your products using this field. For value definitions, see Enumeration - Promotion Type. |
||||||
frequency
frequency, together with frequency_schedule, controls how often people see your ad (only available for REACH ads). For example, frequency = 2 frequency_schedule = 3 means ‘show ads no more than twice every 3 day’. |
||||||
frequency_schedule
frequency, together with frequency, controls how often people see your ad (only available for REACH ads). See frequency fields for more |
||||||
gender
Gender that you want to target. Enum: GENDER_FEMALE,GENDER_MALE,GENDER_UNLIMITED |
||||||
interest_category_v2
Interest classification. If the interest is specified, users that do not meet interest target will be excluded during delivery. Do not specify if you wish to target everyone. Use /tools/interest_category/ endpoint to get the complete list of interest categories.
|
||||||
interest_keywords
IDs of interest keywords that you want to use to target audience. You can get interest keywords IDs by using the /tools/interest_keyword/recommend/ endpoint. For details, see Get interest keywords.
|
||||||
ios_osv
Audience minimum ios version. See Appendix-OS Version for details. |
||||||
ios_quota_type
|
||||||
ios_target_device
The iOS devices that you want to target. 1. UNSET: This is the previous default value of the field. 2. IOS14_MINUS: Devices with iOS 14.4 or earlier version that 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. 3. IOS14_PLUS: Devices with iOS 14.5 and above. The iOS 14 privacy update has been enforced in this group of devices. |
||||||
is_comment_disable
Whether to allow comments on your ads on TikTok. Enum values: 0 (allow), 1 (restrict). The default value is allow |
||||||
is_hfss
Whether the promoted product is HFSS foods (foods that are high in fat, salt, or sugar) |
||||||
is_new_structure
Whether the campaign is a new structure |
||||||
is_share_disable
Whether sharing to third-party platforms is disabled for ads in this ad group. Only valid for R&F ads. |
||||||
languages
Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code.
|
||||||
location
IDs of the locations that you want to target. For enum values, see Location IDs.
|
||||||
modify_time
Time at which the ad group was Modified. |
||||||
operation_system
Device operating systems that you want to target. Only one value is allowed. Enum: ANDROID, IOS
|
||||||
opt_status
Operational status. Enum: DISABLE (ad group is disabled), ENABLE (ad group is enabled), FROZEN (terminated and cannot be used again) |
||||||
optimize_goal
The measurable results that you’d like to drive your ads with. For enum values, see Appendix - Optimization Goal. |
||||||
pacing
You can choose between PACING_MODE_SMOOTH and PACING_MODE_FAST. For PACING_MODE_SMOOTH, the budget is allocated evenly within the scheduled time. PACING_MODE_FAST would consume budget and produce results as soon as possible. When Campaign Budget Optimization (budget_optimize_switch) is on, your setting will be ignored and it will be set as PACING_MODE_SMOOTH. Otherwise, this field is required. |
||||||
package
|
||||||
pangle_audience_package_exclude
IDs 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_flow_package/get/ endpoint. You need to set bind_type to INCLUDE. Do not specify this field and pangle_audience_package_exclude at the same time.
|
||||||
pangle_audience_package_include
IDs 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_flow_package/get/ endpoint. You need to set bind_type to EXCLUDE. Do not specify this field and pangle_audience_package_include at the same time.
|
||||||
pangle_block_app_list_id
Pangle app block list ID.
|
||||||
pixel_id
Pixel ID. Only application for landing pages. |
||||||
placement
The apps where you want to deliver your ads. For enum values, see Enumeration - Placement. If placement_type of the adgroup is PLACEMENT_TYPE_AUTOMATIC (Automatic placement), NONE will be returned for this field.
|
||||||
placement_type
The placement strategy that decides where your ads will be shown. Allowed values: PLACEMENT_TYPE_AUTOMATIC (automatic placement), PLACEMENT_TYPE_NORMAL (manual placement) |
||||||
product_set_id
ProductSet ID of the catalog. 0 means selecting all product sets. Return when the corresponding campaign objective_type is CATALOG_SALES. |
||||||
promotion_website_type
Instant page type in your ad group. Currently, the only supported type is TIKTOK_NATIVE_PAGE, which stands for TikTok instant pages. null means no instant pages are used in the ad group. |
||||||
rf_buy_type
Billing method of Reach & Frequency ad groups. For more details, see Enumeration - Reach & Frequency Buy Type. Returned when objective_type of the related campaign is RF_REACH. |
||||||
rf_predict_cpr
The estimated cost per mile reach. Returned when objective_type of the related campaign is RF_REACH. |
||||||
rf_predict_frequency
The estimated show frequency. Returned when objective_type of the related campaign is RF_REACH. |
||||||
roas_bid
ROAS goal for Value Optimization. |
||||||
schedule_end_time
Ad delivery end time (UTC+0). Format should be YYYY-MM-DD HH:MM:SS |
||||||
schedule_start_time
Ad delivery start time (UTC+0). Format should be YYYY-MM-DD HH:MM:SS |
||||||
schedule_type
The schedule type can be either SCHEDULE_START_END or SCHEDULE_FROM_NOW. If you choose SCHEDULE_START_END, you need to specify a start time and an end time. If you choose SCHEDULE_FROM_NOW, you only need to specify a start time. |
||||||
skip_learning_phase
Whether to skip the learning stage. Optional values include: 0 (not skip), 1 (skip) |
||||||
split_test_adgroup_ids
|
||||||
statistic_type
conversion bid statistic type, bid for EVERYTIME (Each Purchase)/ NONE (Unique Purchase) |
||||||
status
Ad group status(secondary status). For enum values, see Enumeration -Ad Group Status - Secondary Status. Note: This field is not returned in the sandbox environment because the ad group is not actually delivered. |
||||||
targeting_expansion
Settings about targeting expansion
|
||||||
video_download
Whether users can download your video ads on TikTok. Allowed values: ALLOW_DOWNLOAD ,PREVENT_DOWNLOAD Default: ALLOW_DOWNLOAD. |
Replication Method : |
Key-based Incremental |
Replication Key |
modify_time |
Primary Key |
ad_id : adgroup_id : advertiser_id : campaign_id : modify_time |
Official docs : |
ad_format
The creative type. Enum values: SINGLE_IMAGE, SINGLE_VIDEO, CAROUSEL. |
ad_id
Ad ID |
ad_name
Ad Name |
ad_text
The ad text. It is shown to your audience as part of your ad creative, to deliver the message you intend to communicate to them. Keyword match type is exact match. |
adgroup_id
Ad group ID |
adgroup_name
Ad group Name |
advertiser_id
Advertiser ID |
app_name
The display name of app download ad |
call_to_action
For call-to-action text, see Enumeration - Call-to-action. |
campaign_id
Campaign ID |
campaign_name
Campaign Name |
card_id
Image card ID, gift code card ID, or premium badge ID |
click_tracking_url
Click monitoring URL. |
create_time
Time at which the ad was created. |
display_name
The display name of landing page or pure exposure ad |
dpa_fallback_type
In DPA scenario, the fallback behavior of deeplink evokes failed. Return when the corresponding campaign objective_type is CATALOG_SALES. |
dpa_open_url_type
Indicates the source of the direct link used in the ad. This field is returned when the corresponding campaign objective_type is CATALOG_SALES. |
dpa_video_tpl_id
Catalog video template ID. Return when the corresponding campaign objective_type is CATALOG_SALES. |
fallback_type
Fallback Type. If the audience do not have the app installed, you can have them fall back to install the app, or to view a specific web page. Not applicable for Deferred Deeplink. Allowed values: APP_INSTALL, WEBSITE, UNSET. If website is chosen, you need to specify the url via landing_page_url field. |
image_ids
A list of image IDs |
image_mode
|
impression_tracking_url
Display monitoring URL |
is_aco
Whether the ad is an automated ad. Set to true for automated ad and false for non-automated ad |
is_creative_authorized
Whether you grant displaying some of your ads in our TikTok For Business Creative Center. Only valid for non-US advertisers, the default value is false. Note: is_creative_authorized can only be used for video ads. |
is_new_structure
Whether the campaign is a new structure (for the same campaign, the structure of campaign, adgroups and ads are the same) |
item_duet_status
Whether to enable dueting for the Spark Ad post. This field is valid only when promotional_music_disabled is set to false. Enum values: ENABLE, DISABLE. This field is only valid for Spark Ad posts. |
item_stitch_status
Whether to enable stitching for the Spark Ad post. This field is valid only when promotional_music_disabled is set to false. Enum values: ENABLE, DISABLE. This field is only valid for Spark Ad posts. |
landing_page_url
Landing page URL |
landing_page_urls
Multiple landing page URLs |
modify_time
Time at which the ad was Modified. |
open_url
The specific location where you want your audience to go if they have your app installed. See open_url_type for more. |
open_url_type
The open URL type. Allowed values differs based on campaign objectives. Allowed values: NORMAL(supported in Traffic, Conversion & CatalogSales), DEFERRED_DEEPLINK(supported in AppInstall & Catalog Sales). |
opt_status
Operation status, optional values include: DISABLE (the ad is disabled), ENABLE (the ad is enabled), FROZEN (the ad is terminated and cannot be enabled) |
page_id
Instant Page (Instant Form, storefront page, tiktok instant page or app profile page) ID |
playable_url
Playable material url |
profile_image
Avatar URL |
promotional_music_disabled
Whether to disable the promotional use of the music in the Spark Ad post. The default value is true. If you want to allow dueting and stitching for the Spark Ad post, you need to set this field to false. This field is only valid for Spark Ad posts. |
status
Ad status(Secondary status,See Enumeration-Ad Status - Secondary Status. Note: This field is not returned in the sandbox environment because the ad is not actually delivered. |
tiktok_item_id
The ID of the TikTok post to be used as an ad. It can be obtained from Get Spark Ad post endpoint. |
vast_moat
Whether Moat Viewability Verification is enabled for the ad. TikTok has partnered with Moat to launch viewability measurement for Brand Auction and Reach & Frequency In-feed ads purchased on TikTok for Business. |
video_id
The video ID. When TikTok posts are used as ads, video_id is invalid. You can get the the ID of a TikTok post via the tiktok_item_id field |
advertisers
Replication Method : |
Key-based Incremental |
Replication Key |
create_time |
Primary Key |
create_time : id |
Official docs : |
address
Advertiser address information |
balance
Account available balance(The unit is related to the advertiser’s currency type currency |
company
Advertiser’s company name |
contacter
Contact Person |
country
The advertiser’s country |
create_time
Advertiser’s create time |
currency
Type of currency used by advertisers |
description
Brand description, i.e. promotional content |
email
Advertiser contact email, masked format. For example, d*****h@test.com |
id
Advertiser ID |
industry
Advertiser industry category. See Appendix-Industries. |
language
Language used by advertisers |
license_no
License number |
license_url
License preview address, the link is valid for an hour by default. |
name
Advertiser name |
phonenumber
Contact mobile number, desensitised data |
promotion_area
|
promotion_center_city
|
promotion_center_province
|
reason
Reason for rejection |
role
Advertiser role, see Enumeration - Advertiser Role. |
status
Advertiser status, see Enumeration - Advertiser Status. |
telephone
Fixed phone number, desensitised data |
timezone
Ad account time zone including GMT offset. For example, |
ad_insights
Replication Method : |
Key-based Incremental |
Replication Key |
stat_time_day |
Primary Key |
ad_id : adgroup_id : advertiser_id : campaign_id : stat_time_day |
Official docs : |
ad_id
Ad ID |
ad_name
Ad name. Supported in Ad level. |
ad_text
Ad title. Supported in Ad level. |
adgroup_id
Ad group ID. Supported in Ad level. |
adgroup_name
Ad group name. Supported in Ad Group and Ad level. |
advertiser_id
Advertiser ID |
average_video_play
Video Average Watch Time Per Video View. The average time your video was played per single video view, including any time spent replaying the video. |
average_video_play_per_user
Video Average Watch Time Per Person. The average time your video was played per person, including any time spent replaying the video. This metric is estimated. |
campaign_id
Campaign ID. Supported in Ad Group and Ad level. |
campaign_name
Campaign name. Supported in Campaign, Ad Group and Ad level. |
clicks
The number of clicks on your ads. |
clicks_on_music_disc
The number of clicks on the official music in your Boosted TikTok ad during the campaign. Available only if you are on the allowlist for the Boosted TikTok feature. |
comments
Paid Comments. The number of comments your video creative received within 1 day of a user seeing a paid ad. |
conversion
The number of times your ad achieved an outcome, based on the secondary goal you selected. As one campaign may have a number of different secondary goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view. (The total count is calculated based on the time each ad impression occurred.) |
conversion_rate
CPA. The average amount of money you’ve spent on a conversion.(The total count is calculated based on the time each ad impression occurred.) |
cost_per_1000_reached
The average cost to reach 1,000 unique users. This metric is estimated. |
cost_per_100_reached
The average cost to reach 100 unique users. This metric is estimated. |
cost_per_conversion
The average amount of money you’ve spent on a conversion.(The total count is calculated based on the time each ad impression occurred.) |
cost_per_result
The average cost for each result from your ads. As one campaign may have a number of different optimization goals, this metric is not supported at advertiser level or campaign level. Please go to ad groups or ads to view the cost per result. (The total count is calculated based on the time each ad impression occurred.) |
cost_per_secondary_goal_result
The average cost for each secondary goal result from your adverts. As one campaign may have a number of different secondary goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view. (The total count is calculated based on the time each ad impression occurred.) |
cpc
The average amount of money you’ve spent on a click. |
cpm
The average amount of money you’ve spent per 1,000 impressions. |
ctr
The percentage of times people saw your ad and performed a click. |
dpa_target_audience_type
The Audience that DPA products target. Supported at Adgroup or Ad levels in both synchronous and asynchronous reports. |
follows
The number of new followers that were gained within 1 day of a user seeing a paid ad. This metric is only for Boosted TikToks. |
frequency
The average number of times each person saw your ad. |
impressions
The number of times your ads were on screen. |
likes
Paid Likes. The number of likes your video creative received within 1 day of a user seeing a paid ad. |
mobile_app_id
Mobile App ID. Examples are, App Store: https://apps.apple.com/us/app/angry-birds/id343200656; Google Play:https://play.google.com/store/apps/details?id=com.rovio.angrybirds. Supported in Ad Group and Ad level. Returned if the promotion type of one Ad Group is App. |
placement
Placement. Supported in Ad Group and Ad level. |
profile_visits
The number of profile visits the ad drove during the campaign. This metric is only for Boosted TikToks. |
profile_visits_rate
The rate of profile visits per impression the paid ad drove during the campaign. This metric is only for Boosted TikToks. |
promotion_type
It can be app, website, or others. Supported at Adgroup and Ad levels in both synchronous and asynchronous reports. |
reach
The number of unique users who saw your ads at least once. This metric is estimated. |
real_time_conversion
The number of times your ad achieved an outcome, based on the objective and settings you selected. (The total count is based on when the conversion actually happened.) |
real_time_conversion_rate
The percentage of results you received out of all the clicks of your ads. (The total count is based on when the conversion actually happened.) |
real_time_cost_per_conversion
The average amount of money you’ve spent on a conversion. (The total count is based on when the conversion actually happened.) |
real_time_cost_per_result
As a campaign may have different optimization goals, tthis metric is not supported at advertiser level or campaign level. Please go to the ad group section to view the cost per Result. (The total count is based on when the conversion actually happened.) |
real_time_result
The number of times your ad achieved an outcome, based on the optimization goal you selected. As a campaign may have different optimization goals, this metric is not supported at advertiser level or campaign level. Please go to the ad group section to view the result. (The total count is based on when the conversion actually happened.) |
real_time_result_rate
As a campaign may have different optimization goals, this metric is not supported at advertiser level or campaign level. Please go to the ad group section to view the Result Rate. (The total count is based on when the conversion actually happened.) |
result
The number of times your ad achieved an outcome, based on the optimization goal you selected. As one campaign may have a number of different optimization goals, this metric is not supported at advertiser level or campaign level. Please go to ad groups or ads to view the results. (The total count is calculated based on the time each ad impression occurred.) |
result_rate
The percentage of results you achieved out of all of the views/clicks on your ads. As one campaign may have a number of different optimization goals, this metric is not supported at advertiser level or campaign level. Please go to ad groups or ads to view the result rate. (The total count is calculated based on the time each ad impression occurred.) |
secondary_goal_result
The number of times your ad achieved an outcome, based on the secondary goal you selected. As one campaign may have a number of different secondary goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view. (The total count is calculated based on the time each ad impression occurred.) |
secondary_goal_result_rate
The percentage of secondary goal results you achieved out of all of the installs of your adverts. As one campaign may have a number of different secondary goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view. The total count is calculated based on the time each ad impression occurred.. |
shares
Paid Shares. The number of shares your video creative received within 1 day of a user seeing a paid ad. |
spend
Total Cost. The estimated total amount of money you’ve spent on your campaign, ad group or ad during its schedule. |
stat_time_day
|
tt_app_id
TikTok App ID. TikTok App ID, the App ID you used when creating an Ad Group. Supported in Ad Group and Ad level. Returned if the promotion type of one Ad Group is App. |
tt_app_name
TikTok App Name. The name of your TikTok App. Supported in Ad Group and Ad level. Returned if the promotion type of one Ad Group is App. |
video_play_actions
Video Views. The number of times your video starts to play. Replays will not be counted. |
video_views_p100
Video Views at 100%. The number of times your video was played at 100% of its length. Replays will not be counted. |
video_views_p25
Video Views at 25%. The number of times your video was played at 25% of its length. Replays will not be counted. |
video_views_p50
Video Views at 50%. The number of times your video was played at 50% of its length. Replays will not be counted. |
video_views_p75
Video Views at 75%. The number of times your video was played at 75% of its length. Replays will not be counted. |
video_watched_2s
2-Second Video Views. The number of times your video played for at least 2 seconds. Replays will not be counted. |
video_watched_6s
6-Second Video Views. The number of times your video played for at least 6 seconds, or completely played. Replays will not be counted. |
ad_insights_by_age_and_gender
Replication Method : |
Key-based Incremental |
Replication Key |
stat_time_day |
Primary Key |
ad_id : adgroup_id : advertiser_id : age : campaign_id : gender : stat_time_day |
Official docs : |
ad_id
Ad ID |
ad_name
Ad name. Available at Ad level. |
ad_text
Ad title. Available in Ad level. |
adgroup_id
Ad group ID. Avaialble at Ad level. |
adgroup_name
Ad group name. Available at Ad Group and Ad levels. |
advertiser_id
Advertiser ID |
age
|
campaign_id
Campaign ID. Available at Ad Group and Ad levels. |
campaign_name
Campaign name. Available at Campaign, Ad Group and Ad levels. |
clicks
The number of clicks on your ads. |
conversion
The number of times your ad achieved an outcome, based on the secondary goal you selected. As one campaign may have a number of different secondary goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view. (The total count is calculated based on the time each ad impression occurred.) |
conversion_rate
The percentage of results you received out of all the clicks of your ads.(The total count is calculated based on the time each ad impression occurred.) |
cost_per_conversion
The average amount of money you’ve spent on a conversion.(The total count is calculated based on the time each ad impression occurred.) |
cost_per_result
The average cost for each result from your ads. As one campaign may have a number of different optimization goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view the cost per result. (The total count is calculated based on the time each ad impression occurred.) |
cpc
The average amount of money you’ve spent on a click. |
cpm
The average amount of money you’ve spent per 1,000 impressions. |
ctr
The percentage of times people saw your ad and performed a click. |
dpa_target_audience_type
The Audience that DPA products target. Supported at Adgroup or Ad levels in both synchronous and asynchronous reports. |
gender
|
impressions
The number of times your ads were on screen. |
mobile_app_id
Mobile App ID. Examples are, App Store: https://apps.apple.com/us/app/angry-birds/id343200656; Google Play:https://play.google.com/store/apps/details?id=com.rovio.angrybirds. Available at Ad Group and Ad levels. Returned if the promotion type of one Ad Group is App. |
promotion_type
It can be app, website, or others. Supported at Adgroup and Ad levels in both synchronous and asynchronous reports. |
real_time_conversion
|
real_time_conversion_rate
|
real_time_cost_per_conversion
|
real_time_cost_per_result
|
real_time_result
|
real_time_result_rate
|
result
|
result_rate
|
spend
|
stat_time_day
|
tt_app_id
|
tt_app_name
|
user_action
|
ad_insights_by_country
Replication Method : |
Key-based Incremental |
Replication Key |
stat_time_day |
Primary Key |
ad_id : adgroup_id : advertiser_id : campaign_id : country_code : stat_time_day |
Official docs : |
ad_id
Ad ID |
ad_name
Ad name. Available at Ad level. |
ad_text
Ad title. Available in Ad level. |
adgroup_id
Ad group ID. Avaialble at Ad level. |
adgroup_name
Ad group name. Available at Ad Group and Ad levels. |
advertiser_id
Advertiser ID |
campaign_id
Campaign ID. Available at Ad Group and Ad levels. |
campaign_name
Campaign name. Available at Campaign, Ad Group and Ad levels. |
clicks
The number of clicks on your ads. |
conversion
The number of times your ad achieved an outcome, based on the secondary goal you selected. As one campaign may have a number of different secondary goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view. (The total count is calculated based on the time each ad impression occurred.) |
conversion_rate
The percentage of results you received out of all the clicks of your ads.(The total count is calculated based on the time each ad impression occurred.) |
cost_per_conversion
The average amount of money you’ve spent on a conversion.(The total count is calculated based on the time each ad impression occurred.) |
cost_per_result
The average cost for each result from your ads. As one campaign may have a number of different optimization goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view the cost per result. (The total count is calculated based on the time each ad impression occurred.) |
country_code
|
cpc
The average amount of money you’ve spent on a click. |
cpm
The average amount of money you’ve spent per 1,000 impressions. |
ctr
The percentage of times people saw your ad and performed a click. |
dpa_target_audience_type
The Audience that DPA products target. Supported at Adgroup or Ad levels in both synchronous and asynchronous reports. |
impressions
The number of times your ads were on screen. |
mobile_app_id
Mobile App ID. Examples are, App Store: https://apps.apple.com/us/app/angry-birds/id343200656; Google Play:https://play.google.com/store/apps/details?id=com.rovio.angrybirds. Available at Ad Group and Ad levels. Returned if the promotion type of one Ad Group is App. |
promotion_type
It can be app, website, or others. Supported at Adgroup and Ad levels in both synchronous and asynchronous reports. |
real_time_conversion
The number of times your ad achieved an outcome, based on the objective and settings you selected. (The total count is based on when the conversion actually happened.) |
real_time_conversion_rate
The percentage of results you received out of all the clicks of your ads. (The total count is based on when the conversion actually happened.) |
real_time_cost_per_conversion
The average amount of money you’ve spent on a conversion. (The total count is based on when the conversion actually happened.) |
real_time_cost_per_result
As a campaign may have different optimization goals, the total number of result is not supported in campaign section now, please go to the ad group section to view the cost per Result. (The total count is based on when the conversion actually happened.) |
real_time_result
The number of times your ad achieved an outcome, based on the optimization goal you selected. As a campaign may have different optimization goals, the total number of result is not supported in campaign section now ,Please go to the ad group section to view the result. (The total count is based on when the conversion actually happened.) |
real_time_result_rate
As a campaign may have different optimization goals, the total number of result is not supported in campaign section now ,Please go to the ad group section to view the Result Rate. (The total count is based on when the conversion actually happened.) |
result
The number of times your ad achieved an outcome, based on the optimization goal you selected. As one campaign may have a number of different optimization goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view the results. (The total count is calculated based on the time each ad impression occurred.) |
result_rate
The percentage of results you achieved out of all of the views/clicks on your ads. As one campaign may have a number of different optimization goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view the result rate. (The total count is calculated based on the time each ad impression occurred.) |
spend
Total Cost. The estimated total amount of money you’ve spent on your campaign, ad group or ad during its schedule. |
stat_time_day
|
tt_app_id
TikTok App ID. TikTok App ID, the App ID you used when creating an Ad Group. Available at Ad Group and Ad levels. Returned if the promotion type of one Ad Group is App. |
tt_app_name
TikTok App Name. The name of your TikTok App. Available at Ad Group and Ad levels. Returned if the promotion type of one Ad Group is App. |
user_action
For the VIDEO_RELATED scene, available values include WATCHED_TO_END, LIKED, COMMENTED, and SHARED. For the CREATOR_RELATED scene, available values are FOLLOWING and VIEW_HOMEPAGE. |
ad_insights_by_platform
Replication Method : |
Key-based Incremental |
Replication Key |
stat_time_day |
Primary Key |
ad_id : adgroup_id : advertiser_id : campaign_id : platform : stat_time_day |
Official docs : |
ad_id
Ad ID |
ad_name
Ad name. Available at Ad level. |
ad_text
Ad title. Available at Ad level. |
adgroup_id
Ad group ID. Avaialble at Ad level. |
adgroup_name
Ad group name. Available at Ad Group and Ad levels. |
advertiser_id
Advertiser ID |
campaign_id
Campaign ID. Available at Ad Group and Ad levels. |
campaign_name
Campaign name. Available at Campaign, Ad Group and Ad levels. |
clicks
Clicks. The number of clicks on your ads. |
conversion
The number of times your ad achieved an outcome, based on the secondary goal you selected. As one campaign may have a number of different secondary goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view. (The total count is calculated based on the time each ad impression occurred.) |
conversion_rate
The percentage of results you received out of all the clicks of your ads.(The total count is calculated based on the time each ad impression occurred.) |
cost_per_conversion
The average amount of money you’ve spent on a conversion.(The total count is calculated based on the time each ad impression occurred.) |
cost_per_result
The average cost for each result from your ads. As one campaign may have a number of different optimization goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view the cost per result. (The total count is calculated based on the time each ad impression occurred.) |
cpc
The average amount of money you’ve spent on a click. |
cpm
The average amount of money you’ve spent per 1,000 impressions. |
ctr
The percentage of times people saw your ad and performed a click. |
dpa_target_audience_type
The Audience that DPA products target. Supported at Adgroup or Ad levels in both synchronous and asynchronous reports. |
impressions
The number of times your ads were on screen. |
mobile_app_id
Mobile App ID. Examples are, App Store: https://apps.apple.com/us/app/angry-birds/id343200656; Google Play:https://play.google.com/store/apps/details?id=com.rovio.angrybirds. Available at Ad Group and Ad levels. Returned if the promotion type of one Ad Group is App. |
platform
|
promotion_type
It can be app, website, or others. Supported at Adgroup and Ad levels in both synchronous and asynchronous reports. |
real_time_conversion
The number of times your ad achieved an outcome, based on the objective and settings you selected. (The total count is based on when the conversion actually happened.) |
real_time_conversion_rate
The percentage of results you received out of all the clicks of your ads. (The total count is based on when the conversion actually happened.) |
real_time_cost_per_conversion
The average amount of money you’ve spent on a conversion. (The total count is based on when the conversion actually happened.) |
real_time_cost_per_result
As a campaign may have different optimization goals, the total number of result is not supported in campaign section now, please go to the ad group section to view the cost per Result. (The total count is based on when the conversion actually happened.) |
real_time_result
The number of times your ad achieved an outcome, based on the optimization goal you selected. As a campaign may have different optimization goals, the total number of result is not supported in campaign section now ,Please go to the ad group section to view the result. (The total count is based on when the conversion actually happened.) |
real_time_result_rate
As a campaign may have different optimization goals, the total number of result is not supported in campaign section now ,Please go to the ad group section to view the Result Rate. (The total count is based on when the conversion actually happened.) |
result
The number of times your ad achieved an outcome, based on the optimization goal you selected. As one campaign may have a number of different optimization goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view the results. (The total count is calculated based on the time each ad impression occurred.) |
result_rate
The percentage of results you achieved out of all of the views/clicks on your ads. As one campaign may have a number of different optimization goals, this statistic is not supported for campaigns. Please go to ad groups or ads to view the result rate. (The total count is calculated based on the time each ad impression occurred.) |
spend
Total Cost. The estimated total amount of money you’ve spent on your campaign, ad group or ad during its schedule. |
stat_time_day
|
tt_app_id
TikTok App ID. TikTok App ID, the App ID you used when creating an Ad Group. Available at Ad Group and Ad levels. Returned if the promotion type of one Ad Group is App. |
tt_app_name
TikTok App Name. The name of your TikTok App. Available at Ad Group and Ad levels. Returned if the promotion type of one Ad Group is App. |
user_action
For the VIDEO_RELATED scene, available values include WATCHED_TO_END, LIKED, COMMENTED, and SHARED. For the CREATOR_RELATED scene, available values are FOLLOWING and VIEW_HOMEPAGE. |
campaigns
Replication Method : |
Key-based Incremental |
Replication Key |
modify_time |
Primary Key |
advertiser_id : campaign_id : modify_time |
Official docs : |
advertiser_id
Advertiser ID |
bid_type
Bidding strategy on the campaign level. Return only when Campaign Budget Optimization is enabled. |
budget
Campaign budget |
budget_mode
Budget mode. See Enumerations-Budget Mode. |
budget_optimize_switch
Whether Campaign Budget Optimization is enabled. Return only when Campaign Budget Optimization is enabled. For details about Campaign Budget Optimization (CBO), see Campaign Budget Optimization. |
campaign_id
Campaign ID |
campaign_name
Campaign name |
campaign_type
Campaign Type, indicates the campaign is a regular campaign or iOS 14 campaign. Enum values: REGULAR_CAMPAIGN and IOS14_CAMPAIGN. |
create_time
Time at which the campaign was created. |
is_new_structure
Whether the campaign is a new structure (for the same campaign, the structure of campaign, ad groups and ads are the same) |
modify_time
Time at which the campaign was Modified. |
objective
Campaign type (application or landing page). Enum values: APP(application), LANDING_PAGE(Landing page) |
objective_type
Advertising objective. Enum values: APP_PROMOTION, WEB_CONVERSIONS,APP_INSTALL, CONVERSIONS, REACH, TRAFFIC, VIDEO_VIEWS, CATALOG_SALES, ENGAGEMENT, LEAD_GENERATION, SHOP_PURCHASES,RF_REACH, RF_TRAFFIC, RF_VIDEO_VIEW. |
opt_status
Operation status. Enum values: DISABLE, ENABLE |
optimize_goal
Optimization goal. Return only when Campaign Budget Optimization is enabled. |
split_test_variable
|
status
Campaign status (Secondary status). For enum values, see Enumeration-Campaign Status - Secondary Status. Note: This field is not returned in the sandbox environment because the campaign is not actually delivered. |
Related | Troubleshooting |
Questions? Feedback?
Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.