TikTok Ads (v1) | Stitch Documentation

TikTok Ads extraction 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.

ad_insights

Replication Method	Key-based Incremental
Primary Keys	ad_id adgroup_id advertiser_id campaign_id stat_time_day
Replication Key	stat_time_day
Useful links	TikTok Ads documentation ad_insights schema on GitHub

ad_insights table schema

ad_id

STRING

ad_name

STRING

ad_text

STRING

adgroup_id

STRING

adgroup_name

STRING

advertiser_id

STRING

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_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

Replication Method	Key-based Incremental
Primary Keys	ad_id adgroup_id advertiser_id age campaign_id gender stat_time_day
Replication Key	stat_time_day
Useful links	TikTok Ads documentation ad_insights_by_age_and_gender schema on GitHub

ad_insights_by_age_and_gender table schema

ad_id

STRING

ad_name

STRING

ad_text

STRING

adgroup_id

STRING

adgroup_name

STRING

advertiser_id

STRING

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

STRING

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

Replication Method	Key-based Incremental
Primary Keys	ad_id adgroup_id advertiser_id campaign_id country_code stat_time_day
Replication Key	stat_time_day
Useful links	TikTok Ads documentation ad_insights_by_country schema on GitHub

ad_insights_by_country table schema

ad_id

STRING

ad_name

STRING

ad_text

STRING

adgroup_id

STRING

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

STRING

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

Replication Method	Key-based Incremental
Primary Keys	ad_id adgroup_id campaign_id platform stat_time_day
Replication Key	stat_time_day
Useful links	TikTok Ads documentation ad_insights_by_platform schema on GitHub

ad_insights_by_platform table schema

ad_id

STRING

ad_name

STRING

ad_text

STRING

adgroup_id

STRING

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

STRING

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

adgroups

Replication Method	Key-based Incremental
Primary Keys	adgroup_id advertiser_id campaign_id modify_time
Replication Key	modify_time
Useful links	TikTok Ads documentation adgroups schema on GitHub

adgroups table schema

actions

ARRAY

Click to expand actions

action_category_ids

ARRAY

action_period

NUMBER

action_scene

STRING

video_user_actions

ARRAY

adgroup_app_profile_page_state

STRING

adgroup_id

STRING

adgroup_name

STRING

advertiser_id

STRING

age_groups

ARRAY

app_download_url

STRING

app_id

STRING

audience

ARRAY

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

carriers_v2

ARRAY

catalog_authorized_bc

INTEGER

catalog_id

STRING

conversion_bid_price

NUMBER

conversion_window

STRING

cpv_video_duration

STRING

create_time

DATE-TIME

creative_material_mode

STRING

current_status

STRING

dayparting

STRING

deep_bid_type

STRING

deep_cpa_bid

NUMBER

delivery_mode

STRING

device_models

ARRAY

device_price_ranges

ARRAY

excluded_audience

ARRAY

excluded_custom_actions

ARRAY

Click to expand excluded_custom_actions

code

STRING

days

INTEGER

frequency

INTEGER

frequency_schedule

INTEGER

gender

STRING

included_custom_actions

ARRAY

Click to expand included_custom_actions

code

STRING

days

INTEGER

interest_category_v2

ARRAY

interest_keywords

ARRAY

inventory_filter_enabled

BOOLEAN

ios14_targeting

STRING

ios_quota_type

STRING

is_comment_disable

BOOLEAN

is_hfss

BOOLEAN

is_new_structure

BOOLEAN

languages

ARRAY

location

ARRAY

min_android_version

STRING

min_ios_version

STRING

modify_time

DATE-TIME

network_types

ARRAY

next_day_retention

NUMBER

operating_systems

ARRAY

operation_status

STRING

optimization_event

STRING

optimization_goal

STRING

pacing

STRING

package

STRING

pangle_audience_package_exclude

ARRAY

pangle_audience_package_include

ARRAY

pangle_block_app_list_id

ARRAY

pixel_id

STRING

placement_type

STRING

placements

ARRAY

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

DATE-TIME

schedule_start_time

DATE-TIME

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_enabled

BOOLEAN

expansion_types

ARRAY

video_download

STRING

Replication Method	Key-based Incremental
Primary Keys	ad_id adgroup_id advertiser_id campaign_id modify_time
Replication Key	modify_time
Useful links	TikTok Ads documentation ads schema on GitHub

ads table schema

ad_format

STRING

ad_id

STRING

ad_name

STRING

ad_text

STRING

adgroup_id

STRING

adgroup_name

STRING

advertiser_id

STRING

app_name

STRING

brand_safety_vast_url

STRING

call_to_action

STRING

campaign_id

STRING

campaign_name

STRING

card_id

STRING

carousel_image_index

INTEGER

catalog_id

STRING

click_tracking_url

STRING

create_time

DATE-TIME

creative_authorized

BOOLEAN

current_status

STRING

deeplink

STRING

deeplink_type

STRING

display_name

STRING

dynamic_destination

STRING

dynamic_format

STRING

fallback_type

STRING

image_ids

ARRAY

image_mode

STRING

impression_tracking_url

STRING

is_aco

BOOLEAN

is_new_structure

BOOLEAN

item_duet_status

STRING

item_group_ids

ARRAY

item_stitch_status

STRING

landing_page_url

STRING

landing_page_urls

STRING

modify_time

DATE-TIME

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

catalog_id

STRING

item_group_id

STRING

store_id

STRING

sku_ids

STRING

tiktok_item_id

STRING

tracking_app_id

STRING

tracking_offline_event_set_ids

ARRAY

utm_params

ARRAY

Click to expand utm_params

key

STRING

value

STRING

vast_moat_enabled

BOOLEAN

vertical_video_strategy

STRING

video_id

STRING

viewability_postbid_partner

STRING

viewability_vast_url

STRING

advertisers

Replication Method	Key-based Incremental
Primary Keys	advertiser_id create_time
Replication Key	create_time
Useful links	TikTok Ads documentation advertisers schema on GitHub

advertisers table schema

address

STRING

advertiser_account_type

STRING

advertiser_id

STRING

balance

NUMBER

cellphone_number

STRING

company

STRING

contacter

STRING

country

STRING

create_time

STRING

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

campaign_insights_by_province

Replication Method	Key-based Incremental
Primary Keys	advertiser_id campaign_id province_id stat_time_day
Replication Key	stat_time_day
Useful links	TikTok Ads documentation campaign_insights_by_province schema on GitHub

campaign_insights_by_province table schema

advertiser_id

STRING

campaign_budget

STRING

campaign_dedicate_type

STRING

campaign_id

STRING

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

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

campaigns

Replication Method	Key-based Incremental
Primary Keys	advertiser_id campaign_id modify_time
Replication Key	modify_time
Useful links	TikTok Ads documentation campaigns schema on GitHub

campaigns table schema

advertiser_id

STRING

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_name

STRING

campaign_product_source

STRING

campaign_type

STRING

create_time

DATE-TIME

current_status

STRING

deep_bid_type

STRING

is_new_structure

BOOLEAN

is_smart_performance_campaign

BOOLEAN

modify_time

DATE-TIME

objective

STRING

objective_type

STRING

operation_status

STRING

optimization_goal

STRING

rf_campaign_type

STRING

roas_bid

NUMBER

secondary_status

STRING

special_industries

ARRAY

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