TikTok Ads (v1) | Stitch Documentation

TikTok Ads is in beta
TikTok Ads is currently in beta. The info in this guide is subject to change.

TikTok Ads is supported by Stitch
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
Stitch plan	Standard	API availability	Available
Singer GitHub repository	singer-io/tap-tiktok-ads
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

Replication schedules affect the time Extraction begins, not the time to data loaded. Refer to the Replication Scheduling documentation for more information.

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:

Replication Frequency
Anchor Scheduling
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

Is an object missing or not replicating? Verify that the object meets the requirements for selection and replication.

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.

Important: Using the Select All feature will overwrite any previous selections. However, selections aren’t final until Finalize Your Selections is clicked. Clicking Cancel will restore your previous selections. Refer to the Select All guide for more info about this feature.

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.

Replication will continue after the seven days are over. If you’re no longer interested in this source, be sure to pause or delete the integration to prevent unwanted usage.

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

View table schema on GitHub

Replication Method :	Key-based Incremental	Replication Key :	modify_time
Primary Key :	adgroup_name : advertiser_id : campaign_id : modify_time	Official docs :	Official Docs

adgroups table schema

action_v2
ARRAY

A list of action category objects.

Click to expand action_v2

action_categories
ARRAY

IDs of the action categories (behaviors) or hashtags that you want to target. This field is valid only when TikTok placement is the only placement selected.

Click to expand action_categories

items
INTEGER

ID of the action category

adgroups (table), action_categories (attribute)

action_period
INTEGER

The time period to include actions from.

action_scene
STRING

Where you can collect information about user actions. Enum: VIDEO_RELATED, CREATOR_RELATED, HASHTAG_RELATED.

user_actions
ARRAY

Video-related actions.

adgroups (table), action_v2 (attribute)

adgroup_id
INTEGER

Ad group ID

adgroup_name
STRING

Ad group Name

advertiser_id
INTEGER

Advertiser ID

age
ARRAY

Age groups you want to target. For enum values, see Enumeration - Age Group.

Click to expand age

items
STRING

Age group you want to target.

adgroups (table), age (attribute)

android_osv
STRING

Minimum Android version. For enum values, see Enumeration - Minimum Android Version.

app_download_url
STRING

App download link

app_id
INTEGER

The Application ID of the promoted app. You can get app_id by using the /app/list/ endpoint.

audience
ARRAY

A list of audience IDs

Click to expand audience

items
INTEGER

Audience ID

adgroups (table), audience (attribute)

audience_type
STRING

App retargeting audience type. For enum values, see Enumeration - App Retargeting Audience Type.

bid
NUMBER

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
STRING

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
STRING

Bid method. See Enumeration - Bid method for optional values.

brand_safety
STRING

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
STRING

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
NUMBER

Ad budget. Returns 0.0 when Campaign Budget Optimization (budget_optimize_switch) is on.

budget_mode
STRING

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
INTEGER

Impressions to be purchased. Returned when objective_type of the related campaign is RF_REACH.

buy_reach
INTEGER

Purchased user reach. Returned when objective_type of the related campaign is RF_REACH.

campaign_id
INTEGER

Campaign ID

carriers_v2
ARRAY

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.

Click to expand carriers_v2

items
INTEGER

Carrier that you want to target.

adgroups (table), carriers_v2 (attribute)

catalog_authorized_bc
INTEGER

For catalogs in Business Center, this field returns the ID of the Business Center that a catalog belongs to.

catalog_id
INTEGER

Catalog ID。Return when the corresponding campaign objective_type is CATALOG_SALES.

connection_type
ARRAY

Device connection types that you want to target. Default: unlimited. For enum values, see Enumeration - Connection Type.

Click to expand connection_type

items
STRING

Device connection type that you want to target.

adgroups (table), connection_type (attribute)

conversion_bid
NUMBER

Where you can set a target cost per conversion for oCPM(Optimized Cost per Mille).

conversion_window
STRING

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
STRING

Optimized video playback duration. Optional values include: SIX_SECONDS (video playback 6 seconds) and TWO_SECONDS (video playback 2 seconds)

create_time
STRING

Time at which the ad group was created.

creative_material_mode
STRING

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
NUMBER

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
STRING

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
STRING

Bidding strategy for in-app events. For enum values and their decriptions, see Enumeration - Deep-level Bidding Strategy.

deep_cpabid
NUMBER

Specify bid price in this field after you’ve chosen a bidding strategy for in-app events, for example VO_MIN.

deep_external_action
STRING

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
ARRAY

List of device model IDs. For more details about device models, see Enumeration-Device Models.

Click to expand device_models

items
INTEGER

Device model ID

adgroups (table), device_models (attribute)

device_price
ARRAY

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].

Click to expand device_price

items
INTEGER

Device price.

adgroups (table), device_price (attribute)

dpa_retargeting_type
STRING

The types of ad redirection in the catalog. Returned when the corresponding campaign objective_type is CATALOG_SALES.

enable_inventory_filter
BOOLEAN

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
ARRAY

A list of excluded audience IDs.

Click to expand excluded_audience

items
INTEGER

Audience ID

adgroups (table), excluded_audience (attribute)

external_action
STRING

Conversion event for the ad group. See Conversion events for more.

external_type
STRING

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
INTEGER

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
INTEGER

frequency, together with frequency, controls how often people see your ad (only available for REACH ads). See frequency fields for more

gender
STRING

Gender that you want to target. Enum: GENDER_FEMALE,GENDER_MALE,GENDER_UNLIMITED

interest_category_v2
ARRAY

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.

Click to expand interest_category_v2

items
INTEGER

Interest category.

adgroups (table), interest_category_v2 (attribute)

interest_keywords
ARRAY

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.

Click to expand interest_keywords

items
INTEGER

ID of interest keywords that you want to use to target audience.

adgroups (table), interest_keywords (attribute)

ios_osv
STRING

Audience minimum ios version. See Appendix-OS Version for details.

ios_quota_type
STRING

ios_target_device
STRING

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
BOOLEAN

Whether to allow comments on your ads on TikTok. Enum values: 0 (allow), 1 (restrict). The default value is allow

is_hfss
BOOLEAN

Whether the promoted product is HFSS foods (foods that are high in fat, salt, or sugar)

is_new_structure
BOOLEAN

Whether the campaign is a new structure

is_share_disable
BOOLEAN

Whether sharing to third-party platforms is disabled for ads in this ad group. Only valid for R&F ads.

languages
ARRAY

Codes of the languages that you want to target. For the list of languages codes supported, see Enumeration - Language Code.

Click to expand languages

items
STRING

Code of the language that you want to target.

adgroups (table), languages (attribute)

location
ARRAY

IDs of the locations that you want to target. For enum values, see Location IDs.

Click to expand location

items
INTEGER

ID of the location that you want to target.

adgroups (table), location (attribute)

modify_time
STRING

Time at which the ad group was Modified.

operation_system
ARRAY

Device operating systems that you want to target. Only one value is allowed. Enum: ANDROID, IOS

Click to expand operation_system

items
STRING

Device operating system that you want to target.

adgroups (table), operation_system (attribute)

opt_status
STRING

Operational status. Enum: DISABLE (ad group is disabled), ENABLE (ad group is enabled), FROZEN (terminated and cannot be used again)

optimize_goal
STRING

The measurable results that you’d like to drive your ads with. For enum values, see Appendix - Optimization Goal.

pacing
STRING

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
STRING

pangle_audience_package_exclude
ARRAY

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.

Click to expand pangle_audience_package_exclude

items
INTEGER

ID of the Pangle audience that you want to include.

adgroups (table), pangle_audience_package_exclude (attribute)

pangle_audience_package_include
ARRAY

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.

Click to expand pangle_audience_package_include

items
INTEGER

ID of the Pangle audience that you want to exclude.

adgroups (table), pangle_audience_package_include (attribute)

pangle_block_app_list_id
ARRAY

Pangle app block list ID.

Click to expand pangle_block_app_list_id

items
INTEGER

Pangle app block list ID (single).

adgroups (table), pangle_block_app_list_id (attribute)

pixel_id
INTEGER

Pixel ID. Only application for landing pages.

placement
ARRAY

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.

Click to expand placement

items
STRING

The app where you want to deliver your ads.

adgroups (table), placement (attribute)

placement_type
STRING

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
INTEGER

ProductSet ID of the catalog. 0 means selecting all product sets. Return when the corresponding campaign objective_type is CATALOG_SALES.

promotion_website_type
STRING

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
STRING

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
INTEGER

The estimated cost per mile reach. Returned when objective_type of the related campaign is RF_REACH.

rf_predict_frequency
INTEGER

The estimated show frequency. Returned when objective_type of the related campaign is RF_REACH.

roas_bid
NUMBER

ROAS goal for Value Optimization.

schedule_end_time
STRING

Ad delivery end time (UTC+0). Format should be YYYY-MM-DD HH:MM:SS

schedule_start_time
STRING

Ad delivery start time (UTC+0). Format should be YYYY-MM-DD HH:MM:SS

schedule_type
STRING

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
INTEGER

Whether to skip the learning stage. Optional values include: 0 (not skip), 1 (skip)

split_test_adgroup_ids
ARRAY

Click to expand split_test_adgroup_ids

items
INTEGER

adgroups (table), split_test_adgroup_ids (attribute)

statistic_type
STRING

conversion bid statistic type, bid for EVERYTIME (Each Purchase)/ NONE (Unique Purchase)

status
STRING

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
OBJECT

Settings about targeting expansion

Click to expand targeting_expansion

expansion_types
ARRAY

The target audience types that you want to expand

Click to expand expansion_types

items
STRING

The target audience type that you want to expand

adgroups (table), expansion_types (attribute)

enable_expansion
BOOLEAN

Whether to enable targeting expansion

adgroups (table), targeting_expansion (attribute)

video_download
STRING

Whether users can download your video ads on TikTok. Allowed values: ALLOW_DOWNLOAD ,PREVENT_DOWNLOAD Default: ALLOW_DOWNLOAD.

View table schema on GitHub

Replication Method :	Key-based Incremental	Replication Key :	modify_time
Primary Key :	ad_id : adgroup_id : advertiser_id : campaign_id : modify_time	Official docs :	Official Docs

ads table schema

ad_format
STRING

The creative type. Enum values: SINGLE_IMAGE, SINGLE_VIDEO, CAROUSEL.

ad_id
INTEGER

Ad ID

ad_name
STRING

Ad Name

ad_text
STRING

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
INTEGER

Ad group ID

adgroup_name
STRING

Ad group Name

advertiser_id
INTEGER

Advertiser ID

app_name
STRING

The display name of app download ad

call_to_action
STRING

For call-to-action text, see Enumeration - Call-to-action.

campaign_id
INTEGER

Campaign ID

campaign_name
STRING

Campaign Name

card_id
INTEGER

Image card ID, gift code card ID, or premium badge ID

click_tracking_url
STRING

Click monitoring URL.

create_time
STRING

Time at which the ad was created.

display_name
STRING

The display name of landing page or pure exposure ad

dpa_fallback_type
STRING

In DPA scenario, the fallback behavior of deeplink evokes failed. Return when the corresponding campaign objective_type is CATALOG_SALES.

dpa_open_url_type
STRING

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
STRING

Catalog video template ID. Return when the corresponding campaign objective_type is CATALOG_SALES.

fallback_type
STRING

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
ARRAY

A list of image IDs

Click to expand image_ids

items
STRING

Image ID

ads (table), image_ids (attribute)

image_mode
STRING

impression_tracking_url
STRING

Display monitoring URL

is_aco
BOOLEAN

Whether the ad is an automated ad. Set to true for automated ad and false for non-automated ad

is_creative_authorized
BOOLEAN

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
BOOLEAN

Whether the campaign is a new structure (for the same campaign, the structure of campaign, adgroups and ads are the same)

item_duet_status
STRING

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
STRING

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
STRING

Landing page URL

landing_page_urls
STRING

Multiple landing page URLs

modify_time
STRING

Time at which the ad was Modified.

open_url
STRING

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
STRING

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
STRING

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
INTEGER

Instant Page (Instant Form, storefront page, tiktok instant page or app profile page) ID

playable_url
STRING

Playable material url

profile_image
STRING

Avatar URL

promotional_music_disabled
BOOLEAN

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
STRING

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
STRING

The ID of the TikTok post to be used as an ad. It can be obtained from Get Spark Ad post endpoint.

vast_moat
BOOLEAN

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
STRING

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

View table schema on GitHub

Replication Method :	Key-based Incremental	Replication Key :	create_time
Primary Key :	create_time : id	Official docs :	Official Docs

advertisers table schema

address
STRING

Advertiser address information

balance
NUMBER

Account available balance（The unit is related to the advertiser’s currency type currency

company
STRING

Advertiser’s company name

contacter
STRING

Contact Person

country
STRING

The advertiser’s country

create_time
STRING

Advertiser’s create time

currency
STRING

Type of currency used by advertisers

description
STRING

Brand description, i.e. promotional content

email
STRING

Advertiser contact email, masked format. For example, d*****h@test.com

id
INTEGER

Advertiser ID

industry
STRING

Advertiser industry category. See Appendix-Industries.

language
STRING

Language used by advertisers

license_no
STRING

License number

license_url
STRING

License preview address, the link is valid for an hour by default.

name
STRING

Advertiser name

phonenumber
STRING

Contact mobile number, desensitised data

promotion_area
STRING

promotion_center_city
STRING

promotion_center_province
STRING

reason
STRING

Reason for rejection

role
STRING

Advertiser role, see Enumeration - Advertiser Role.

status
STRING

Advertiser status, see Enumeration - Advertiser Status.

telephone
STRING

Fixed phone number, desensitised data

timezone
STRING

Ad account time zone including GMT offset. For example, Etc/GMT

ad_insights

View table schema on GitHub

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 :	Official Docs

ad_insights table schema

ad_id
INTEGER

Ad ID

ad_name
STRING

Ad name. Supported in Ad level.

ad_text
STRING

Ad title. Supported in Ad level.

adgroup_id
INTEGER

Ad group ID. Supported in Ad level.

adgroup_name
STRING

Ad group name. Supported in Ad Group and Ad level.

advertiser_id
INTEGER

Advertiser ID

average_video_play
NUMBER

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
NUMBER

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
INTEGER

Campaign ID. Supported in Ad Group and Ad level.

campaign_name
STRING

Campaign name. Supported in Campaign, Ad Group and Ad level.

clicks
INTEGER

The number of clicks on your ads.

clicks_on_music_disc
INTEGER

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
INTEGER

Paid Comments. The number of comments your video creative received within 1 day of a user seeing a paid ad.

conversion
INTEGER

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
NUMBER

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
STRING

The average cost to reach 1,000 unique users. This metric is estimated.

cost_per_100_reached
NUMBER

The average cost to reach 100 unique users. This metric is estimated.

cost_per_conversion
NUMBER

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
NUMBER

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
NUMBER

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
NUMBER

The average amount of money you’ve spent on a click.

cpm
NUMBER

The average amount of money you’ve spent per 1,000 impressions.

ctr
NUMBER

The percentage of times people saw your ad and performed a click.

dpa_target_audience_type
STRING

The Audience that DPA products target. Supported at Adgroup or Ad levels in both synchronous and asynchronous reports.

follows
INTEGER

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
NUMBER

The average number of times each person saw your ad.

impressions
INTEGER

The number of times your ads were on screen.

likes
INTEGER

Paid Likes. The number of likes your video creative received within 1 day of a user seeing a paid ad.

mobile_app_id
STRING

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
STRING

Placement. Supported in Ad Group and Ad level.

profile_visits
INTEGER

The number of profile visits the ad drove during the campaign. This metric is only for Boosted TikToks.

profile_visits_rate
NUMBER

The rate of profile visits per impression the paid ad drove during the campaign. This metric is only for Boosted TikToks.

promotion_type
STRING

It can be app, website, or others. Supported at Adgroup and Ad levels in both synchronous and asynchronous reports.

reach
INTEGER

The number of unique users who saw your ads at least once. This metric is estimated.

real_time_conversion
INTEGER

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
NUMBER

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
NUMBER

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
NUMBER

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
INTEGER

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
NUMBER

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
INTEGER

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
NUMBER

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
INTEGER

secondary_goal_result_rate
NUMBER

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
INTEGER

Paid Shares. The number of shares your video creative received within 1 day of a user seeing a paid ad.

spend
NUMBER

Total Cost. The estimated total amount of money you’ve spent on your campaign, ad group or ad during its schedule.

stat_time_day
STRING

tt_app_id
STRING

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
STRING

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
INTEGER

Video Views. The number of times your video starts to play. Replays will not be counted.

video_views_p100
INTEGER

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
INTEGER

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
INTEGER

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
INTEGER

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
INTEGER

2-Second Video Views. The number of times your video played for at least 2 seconds. Replays will not be counted.

video_watched_6s
INTEGER

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

View table schema on GitHub

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 :	Official Docs

ad_insights_by_age_and_gender table schema

ad_id
INTEGER

Ad ID

ad_name
STRING

Ad name. Available at Ad level.

ad_text
STRING

Ad title. Available in Ad level.

adgroup_id
INTEGER

Ad group ID. Avaialble at Ad level.

adgroup_name
STRING

Ad group name. Available at Ad Group and Ad levels.

advertiser_id
INTEGER

Advertiser ID

age
STRING

campaign_id
INTEGER

Campaign ID. Available at Ad Group and Ad levels.

campaign_name
STRING

Campaign name. Available at Campaign, Ad Group and Ad levels.

clicks
INTEGER

The number of clicks on your ads.

conversion
INTEGER

conversion_rate
NUMBER

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
NUMBER

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
NUMBER

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
NUMBER

The average amount of money you’ve spent on a click.

cpm
NUMBER

The average amount of money you’ve spent per 1,000 impressions.

ctr
NUMBER

The percentage of times people saw your ad and performed a click.

dpa_target_audience_type
STRING

The Audience that DPA products target. Supported at Adgroup or Ad levels in both synchronous and asynchronous reports.

gender
STRING

impressions
INTEGER

The number of times your ads were on screen.

mobile_app_id
STRING

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
STRING

It can be app, website, or others. Supported at Adgroup and Ad levels in both synchronous and asynchronous reports.

real_time_conversion
INTEGER

real_time_conversion_rate
NUMBER

real_time_cost_per_conversion
NUMBER

real_time_cost_per_result
NUMBER

real_time_result
INTEGER

real_time_result_rate
NUMBER

result
INTEGER

result_rate
NUMBER

spend
NUMBER

stat_time_day
STRING

tt_app_id
STRING

tt_app_name
STRING

user_action
STRING

ad_insights_by_country

View table schema on GitHub

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 :	Official Docs

ad_insights_by_country table schema

ad_id
INTEGER

Ad ID

ad_name
STRING

Ad name. Available at Ad level.

ad_text
STRING

Ad title. Available in Ad level.

adgroup_id
INTEGER

Ad group ID. Avaialble at Ad level.

adgroup_name
STRING

Ad group name. Available at Ad Group and Ad levels.

advertiser_id
INTEGER

Advertiser ID

campaign_id
INTEGER

Campaign ID. Available at Ad Group and Ad levels.

campaign_name
STRING

Campaign name. Available at Campaign, Ad Group and Ad levels.

clicks
INTEGER

The number of clicks on your ads.

conversion
INTEGER

conversion_rate
NUMBER

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
NUMBER

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
NUMBER

country_code
STRING

cpc
NUMBER

The average amount of money you’ve spent on a click.

cpm
NUMBER

The average amount of money you’ve spent per 1,000 impressions.

ctr
NUMBER

The percentage of times people saw your ad and performed a click.

dpa_target_audience_type
STRING

The Audience that DPA products target. Supported at Adgroup or Ad levels in both synchronous and asynchronous reports.

impressions
INTEGER

The number of times your ads were on screen.

mobile_app_id
STRING

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
STRING

It can be app, website, or others. Supported at Adgroup and Ad levels in both synchronous and asynchronous reports.

real_time_conversion
INTEGER

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
NUMBER

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
NUMBER

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
NUMBER

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
INTEGER

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
NUMBER

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
INTEGER

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
NUMBER

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
NUMBER

Total Cost. The estimated total amount of money you’ve spent on your campaign, ad group or ad during its schedule.

stat_time_day
STRING

tt_app_id
STRING

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
STRING

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
STRING

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

View table schema on GitHub

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 :	Official Docs

ad_insights_by_platform table schema

ad_id
INTEGER

Ad ID

ad_name
STRING

Ad name. Available at Ad level.

ad_text
STRING

Ad title. Available at Ad level.

adgroup_id
INTEGER

Ad group ID. Avaialble at Ad level.

adgroup_name
STRING

Ad group name. Available at Ad Group and Ad levels.

advertiser_id
INTEGER

Advertiser ID

campaign_id
INTEGER

Campaign ID. Available at Ad Group and Ad levels.

campaign_name
STRING

Campaign name. Available at Campaign, Ad Group and Ad levels.

clicks
INTEGER

Clicks. The number of clicks on your ads.

conversion
INTEGER

conversion_rate
NUMBER

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
NUMBER

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
NUMBER

cpc
NUMBER

The average amount of money you’ve spent on a click.

cpm
NUMBER

The average amount of money you’ve spent per 1,000 impressions.

ctr
NUMBER

The percentage of times people saw your ad and performed a click.

dpa_target_audience_type
STRING

The Audience that DPA products target. Supported at Adgroup or Ad levels in both synchronous and asynchronous reports.

impressions
INTEGER

The number of times your ads were on screen.

mobile_app_id
STRING

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
STRING

promotion_type
STRING

It can be app, website, or others. Supported at Adgroup and Ad levels in both synchronous and asynchronous reports.

real_time_conversion
INTEGER

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
NUMBER

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
NUMBER

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
NUMBER

real_time_result
INTEGER

real_time_result_rate
NUMBER

result
INTEGER

result_rate
NUMBER

spend
NUMBER

Total Cost. The estimated total amount of money you’ve spent on your campaign, ad group or ad during its schedule.

stat_time_day
STRING

tt_app_id
STRING

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
STRING

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
STRING

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

View table schema on GitHub

Replication Method :	Key-based Incremental	Replication Key :	modify_time
Primary Key :	advertiser_id : campaign_id : modify_time	Official docs :	Official Docs

campaigns table schema

advertiser_id
INTEGER

Advertiser ID

bid_type
STRING

Bidding strategy on the campaign level. Return only when Campaign Budget Optimization is enabled.

budget
NUMBER

Campaign budget

budget_mode
STRING

Budget mode. See Enumerations-Budget Mode.

budget_optimize_switch
NUMBER

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
INTEGER

Campaign ID

campaign_name
STRING

Campaign name

campaign_type
STRING

Campaign Type, indicates the campaign is a regular campaign or iOS 14 campaign. Enum values: REGULAR_CAMPAIGN and IOS14_CAMPAIGN.

create_time
STRING

Time at which the campaign was created.

is_new_structure
BOOLEAN

Whether the campaign is a new structure (for the same campaign, the structure of campaign, ad groups and ads are the same)

modify_time
STRING

Time at which the campaign was Modified.

objective
STRING

Campaign type (application or landing page). Enum values: APP(application), LANDING_PAGE(Landing page)

objective_type
STRING

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
STRING

Operation status. Enum values: DISABLE, ENABLE

optimize_goal
STRING

Optimization goal. Return only when Campaign Budget Optimization is enabled.

split_test_variable
STRING

status
STRING

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.

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.

Related	Troubleshooting
Destination & Integration Compatibility Replication Scheduling Syncing Historical SaaS Data Resetting Replication Keys Nested Data Structures & Row Count Impact	Third-Party Downtime Understanding & Reducing Your Usage Re-Authorizing Integrations Replication Issues