TikTok Ads (v1) | Stitch Documentation

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.3). 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	Released on February 9, 2023	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.
Check the include_deleted box to have Stitch replicate data from deleted campaigns, ads, and adgroups.

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_id : advertiser_id : campaign_id : modify_time	Official docs :	Official Docs

adgroups table schema

actions
ARRAY

Click to expand actions

action_category_ids
ARRAY

Click to expand action_category_ids

items
STRING

adgroups (table), action_category_ids (attribute)

action_period
NUMBER

action_scene
STRING

video_user_actions
ARRAY

adgroups (table), actions (attribute)

adgroup_app_profile_page_state
STRING

adgroup_id
STRING

Ad group ID

adgroup_name
STRING

advertiser_id
STRING

Advertiser ID

age_groups
ARRAY

Click to expand age_groups

items
STRING

adgroups (table), age_groups (attribute)

app_download_url
STRING

app_id
STRING

audience
ARRAY

Click to expand audience

items
INTEGER

adgroups (table), audience (attribute)

audience_type
STRING

bid_price
NUMBER

bid_type
STRING

billing_event
STRING

brand_safety_partner
STRING

brand_safety_type
STRING

budget
NUMBER

budget_mode
STRING

campaign_id
STRING

Campaign ID

carriers_v2
ARRAY

Click to expand carriers_v2

items
INTEGER

adgroups (table), carriers_v2 (attribute)

catalog_authorized_bc
INTEGER

catalog_id
STRING

conversion_bid_price
NUMBER

conversion_window
STRING

cpv_video_duration
STRING

create_time
STRING

creative_material_mode
STRING

dayparting
STRING

deep_bid_type
STRING

deep_cpa_bid
NUMBER

delivery_mode
STRING

device_models
ARRAY

Click to expand device_models

items
INTEGER

adgroups (table), device_models (attribute)

device_price_ranges
ARRAY

Click to expand device_price_ranges

items
NUMBER

adgroups (table), device_price_ranges (attribute)

excluded_audience
ARRAY

Click to expand excluded_audience

items
INTEGER

adgroups (table), excluded_audience (attribute)

excluded_custom_actions
ARRAY

Click to expand excluded_custom_actions

code
STRING

days
INTEGER

adgroups (table), excluded_custom_actions (attribute)

frequency
INTEGER

frequency_schedule
INTEGER

gender
STRING

included_custom_actions
ARRAY

Click to expand included_custom_actions

code
STRING

days
INTEGER

adgroups (table), included_custom_actions (attribute)

interest_category_v2
ARRAY

Click to expand interest_category_v2

items
INTEGER

adgroups (table), interest_category_v2 (attribute)

interest_keywords
ARRAY

Click to expand interest_keywords

items
INTEGER

adgroups (table), interest_keywords (attribute)

inventory_filter_enabled
BOOLEAN

ios14_targeting
STRING

ios_quota_type
STRING

is_comment_disable
BOOLEAN

is_hfss
BOOLEAN

is_new_structure
BOOLEAN

languages
ARRAY

Click to expand languages

items
STRING

adgroups (table), languages (attribute)

location
ARRAY

Click to expand location

items
INTEGER

adgroups (table), location (attribute)

min_android_version
STRING

min_ios_version
STRING

modify_time
DATE-TIME

Time at which the ad group was Modified.

network_types
ARRAY

Click to expand network_types

items
STRING

adgroups (table), network_types (attribute)

next_day_retention
NUMBER

operating_systems
ARRAY

Click to expand operating_systems

items
STRING

adgroups (table), operating_systems (attribute)

operation_status
STRING

optimization_event
STRING

optimization_goal
STRING

pacing
STRING

package
STRING

pangle_audience_package_exclude
ARRAY

Click to expand pangle_audience_package_exclude

items
INTEGER

adgroups (table), pangle_audience_package_exclude (attribute)

pangle_audience_package_include
ARRAY

Click to expand pangle_audience_package_include

items
INTEGER

adgroups (table), pangle_audience_package_include (attribute)

pangle_block_app_list_id
ARRAY

Click to expand pangle_block_app_list_id

items
INTEGER

adgroups (table), pangle_block_app_list_id (attribute)

pixel_id
STRING

placement_type
STRING

placements
ARRAY

Click to expand placements

items
STRING

adgroups (table), placements (attribute)

product_set_id
STRING

promotion_type
STRING

promotion_website_type
STRING

purchased_impression
NUMBER

purchased_reach
NUMBER

rf_estimated_cpr
NUMBER

rf_estimated_frequency
NUMBER

rf_purchased_type
STRING

roas_bid
NUMBER

schedule_end_time
STRING

schedule_start_time
STRING

schedule_type
STRING

secondary_optimization_event
STRING

secondary_status
STRING

share_disabled
BOOLEAN

shopping_ads_retargeting_type
STRING

skip_learning_phase
BOOLEAN

statistic_type
STRING

targeting_expansion
OBJECT

Click to expand targeting_expansion

expansion_types
ARRAY

Click to expand expansion_types

items
STRING

adgroups (table), expansion_types (attribute)

expansion_enabled
BOOLEAN

adgroups (table), targeting_expansion (attribute)

video_download
STRING

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

ad_id
STRING

Ad ID

ad_name
STRING

ad_text
STRING

adgroup_id
STRING

Ad group ID

adgroup_name
STRING

advertiser_id
STRING

Advertiser ID

app_name
STRING

brand_safety_vast_url
STRING

call_to_action
STRING

campaign_id
STRING

Campaign ID

campaign_name
STRING

card_id
STRING

carousel_image_index
INTEGER

catalog_id
STRING

click_tracking_url
STRING

create_time
STRING

creative_authorized
BOOLEAN

deeplink
STRING

deeplink_type
STRING

display_name
STRING

dynamic_destination
STRING

dynamic_format
STRING

fallback_type
STRING

image_ids
ARRAY

Click to expand image_ids

items
STRING

ads (table), image_ids (attribute)

image_mode
STRING

impression_tracking_url
STRING

is_aco
BOOLEAN

is_new_structure
BOOLEAN

item_duet_status
STRING

item_group_ids
ARRAY

Click to expand item_group_ids

items
STRING

ads (table), item_group_ids (attribute)

item_stitch_status
STRING

landing_page_url
STRING

landing_page_urls
STRING

modify_time
DATE-TIME

Time at which the ad was Modified.

music_id
STRING

operation_status
STRING

page_id
NUMBER

playable_url
STRING

product_set_id
STRING

product_specific_type
STRING

profile_image_url
STRING

promotional_music_disabled
BOOLEAN

secondary_status
STRING

shopping_ads_fallback_type
STRING

shopping_ads_video_package_id
STRING

shopping_deeplink_type
STRING

showcase_products
ARRAY

Click to expand showcase_products

item_group_id
STRING

store_id
STRING

catalog_id
STRING

ads (table), showcase_products (attribute)

sku_ids
STRING

tiktok_item_id
STRING

tracking_app_id
STRING

tracking_offline_event_set_ids
ARRAY

Click to expand tracking_offline_event_set_ids

items
STRING

ads (table), tracking_offline_event_set_ids (attribute)

utm_params
ARRAY

Click to expand utm_params

key
STRING

value
STRING

ads (table), utm_params (attribute)

vast_moat_enabled
BOOLEAN

vertical_video_strategy
STRING

video_id
STRING

viewability_postbid_partner
STRING

viewability_vast_url
STRING

advertisers

View table schema on GitHub

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

advertisers table schema

address
STRING

advertiser_account_type
STRING

advertiser_id
STRING

Advertiser ID

balance
NUMBER

cellphone_number
STRING

company
STRING

contacter
STRING

country
STRING

create_time
STRING

Advertiser’s create time

currency
STRING

description
STRING

email
STRING

industry
STRING

language
STRING

license_no
STRING

license_url
STRING

name
STRING

promotion_area
STRING

promotion_center_city
STRING

promotion_center_province
STRING

rejection_reason
STRING

role
STRING

status
STRING

telephone_number
STRING

timezone
STRING

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
STRING

Ad ID

ad_name
STRING

ad_text
STRING

adgroup_id
STRING

Ad group ID. Supported in Ad level.

adgroup_name
STRING

advertiser_id
STRING

Advertiser ID

app_promotion_type
STRING

average_video_play
NUMBER

average_video_play_per_user
NUMBER

bid
STRING

bid_strategy
STRING

billing_event
STRING

budget
STRING

call_to_action
STRING

campaign_budget
STRING

campaign_dedicate_type
STRING

campaign_id
STRING

Campaign ID. Supported in Ad Group and Ad level.

campaign_name
STRING

clicks
INTEGER

clicks_on_music_disc
INTEGER

comments
INTEGER

conversion
INTEGER

conversion_rate
NUMBER

conversion_rate_v2
NUMBER

cost_per_1000_reached
STRING

cost_per_100_reached
NUMBER

cost_per_conversion
NUMBER

cost_per_result
NUMBER

cost_per_secondary_goal_result
NUMBER

cpc
NUMBER

cpm
NUMBER

ctr
NUMBER

dpa_target_audience_type
STRING

follows
INTEGER

frequency
NUMBER

gross_impressions
STRING

image_mode
STRING

impressions
INTEGER

is_smart_creative
BOOLEAN

likes
INTEGER

mobile_app_id
STRING

objective_type
STRING

opt_status
STRING

placement_type
STRING

profile_visits
INTEGER

profile_visits_rate
NUMBER

promotion_type
STRING

reach
INTEGER

real_time_conversion
INTEGER

real_time_conversion_rate
NUMBER

real_time_conversion_rate_v2
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

secondary_goal_result
INTEGER

secondary_goal_result_rate
NUMBER

shares
INTEGER

smart_target
STRING

spend
NUMBER

split_test
STRING

stat_time_day
DATE-TIME

tt_app_id
STRING

tt_app_name
STRING

video_play_actions
INTEGER

video_views_p100
INTEGER

video_views_p25
INTEGER

video_views_p50
INTEGER

video_views_p75
INTEGER

video_watched_2s
INTEGER

video_watched_6s
INTEGER

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_text
STRING

adgroup_id
INTEGER

Ad group ID. Avaialble at Ad level.

adgroup_name
STRING

advertiser_id
INTEGER

Advertiser ID

age
STRING

bid
STRING

bid_strategy
STRING

billing_event
STRING

budget
STRING

call_to_action
STRING

campaign_budget
STRING

campaign_dedicate_type
STRING

campaign_id
INTEGER

Campaign ID. Available at Ad Group and Ad levels.

campaign_name
STRING

clicks
INTEGER

conversion
INTEGER

conversion_rate
NUMBER

conversion_rate_v2
NUMBER

cost_per_conversion
NUMBER

cost_per_result
NUMBER

cpc
NUMBER

cpm
NUMBER

ctr
NUMBER

dpa_target_audience_type
STRING

gender
STRING

gross_impressions
STRING

impressions
INTEGER

is_smart_creative
BOOLEAN

mobile_app_id
STRING

objective_type
STRING

opt_status
STRING

promotion_type
STRING

real_time_conversion
INTEGER

real_time_conversion_rate
NUMBER

real_time_conversion_rate_v2
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

rf_campaign_type
STRING

smart_target
STRING

spend
NUMBER

split_test
STRING

stat_time_day
DATE-TIME

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_text
STRING

adgroup_id
INTEGER

Ad group ID. Avaialble at Ad level.

adgroup_name
STRING

advertiser_id
INTEGER

Advertiser ID

bid
STRING

bid_strategy
STRING

billing_event
STRING

budget
STRING

call_to_action
STRING

campaign_budget
STRING

campaign_dedicate_type
STRING

campaign_id
INTEGER

Campaign ID. Available at Ad Group and Ad levels.

campaign_name
STRING

clicks
INTEGER

conversion
INTEGER

conversion_rate
NUMBER

conversion_rate_v2
NUMBER

cost_per_conversion
NUMBER

cost_per_result
NUMBER

country_code
STRING

cpc
NUMBER

cpm
NUMBER

ctr
NUMBER

dpa_target_audience_type
STRING

gross_impressions
STRING

impressions
INTEGER

is_smart_creative
BOOLEAN

mobile_app_id
STRING

objective_type
STRING

opt_status
STRING

promotion_type
STRING

real_time_conversion
INTEGER

real_time_conversion_rate
NUMBER

real_time_conversion_rate_v2
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

rf_campaign_type
STRING

smart_target
STRING

spend
NUMBER

split_test
STRING

stat_time_day
DATE-TIME

tt_app_id
STRING

tt_app_name
STRING

user_action
STRING

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 : 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_text
STRING

adgroup_id
INTEGER

Ad group ID. Avaialble at Ad level.

adgroup_name
STRING

advertiser_id
STRING

bid
STRING

bid_strategy
STRING

billing_event
STRING

budget
STRING

call_to_action
STRING

campaign_budget
STRING

campaign_dedicate_type
STRING

campaign_id
INTEGER

Campaign ID. Available at Ad Group and Ad levels.

campaign_name
STRING

clicks
INTEGER

conversion
INTEGER

conversion_rate
NUMBER

conversion_rate_v2
NUMBER

cost_per_conversion
NUMBER

cost_per_result
NUMBER

cpc
NUMBER

cpm
NUMBER

ctr
NUMBER

dpa_target_audience_type
STRING

gross_impressions
STRING

impressions
INTEGER

is_smart_creative
BOOLEAN

mobile_app_id
STRING

objective_type
STRING

opt_status
STRING

platform
STRING

promotion_type
STRING

real_time_conversion
INTEGER

real_time_conversion_rate
NUMBER

real_time_conversion_rate_v2
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

rf_campaign_type
STRING

smart_target
STRING

spend
NUMBER

split_test
STRING

stat_time_day
DATE-TIME

tt_app_id
STRING

tt_app_name
STRING

user_action
STRING

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
STRING

Advertiser ID

app_id
STRING

app_promotion_type
STRING

bid_type
STRING

budget
NUMBER

budget_mode
STRING

budget_optimize_on
BOOLEAN

campaign_app_profile_page_state
STRING

campaign_id
STRING

Campaign ID

campaign_name
STRING

campaign_product_source
STRING

campaign_type
STRING

create_time
STRING

deep_bid_type
STRING

is_new_structure
BOOLEAN

is_smart_performance_campaign
BOOLEAN

modify_time
DATE-TIME

Time at which the campaign was Modified.

objective
STRING

objective_type
STRING

operation_status
STRING

optimization_goal
STRING

rf_campaign_type
STRING

roas_bid
NUMBER

secondary_status
STRING

special_industries
ARRAY

Click to expand special_industries

items
STRING

campaigns (table), special_industries (attribute)

campaign_insights_by_province

View table schema on GitHub

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

campaign_insights_by_province table schema

advertiser_id
STRING

Advertiser ID

campaign_budget
STRING

campaign_dedicate_type
STRING

campaign_id
STRING

Campaign ID

campaign_name
STRING

clicks
INTEGER

conversion
INTEGER

conversion_rate
NUMBER

conversion_rate_v2
NUMBER

cost_per_conversion
NUMBER

cost_per_result
NUMBER

cpc
NUMBER

cpm
NUMBER

ctr
NUMBER

gross_impressions
STRING

impressions
INTEGER

objective_type
STRING

province_id
STRING

Province ID

real_time_conversion
INTEGER

real_time_conversion_rate
NUMBER

real_time_conversion_rate_v2
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

rf_campaign_type
STRING

spend
NUMBER

split_test
STRING

stat_time_day
DATE-TIME

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