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

  1. Sign into your Stitch account.
  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the TikTok Ads icon.

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

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

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:

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

  1. 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.
  2. Click Sign in with TikTok to connect.
  3. Sign in with your TikTok account.
  4. 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.
  5. When finished, click Check and Save, then click All Done.

Step 5: Set objects to replicate

The last step is to select the tables and columns you want to replicate. Learn about the available tables for this integration.

Note: If a replication job is currently in progress, new selections won’t be used until the next job starts.

For TikTok Ads integrations, you can select:

  1. Individual tables and columns

  2. All tables and columns

Click the tabs to view instructions for each selection method.

  1. In the integration’s Tables to Replicate tab, locate a table you want to replicate.
  2. To track a table, click the checkbox next to the table’s name. A blue checkmark means the table is set to replicate.

  3. To track a column, click the checkbox next to the column’s name. A blue checkmark means the column is set to replicate.

  4. Repeat this process for all the tables and columns you want to replicate.
  5. When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.
  1. Click into the integration from the Stitch Dashboard page.
  2. Click the Tables to Replicate tab.

  3. In the list of tables, click the box next to the Table Names column.
  4. In the menu that displays, click Track all Tables and Fields:

    The Track all Tables and Fields menu in the Tables to Replicate tab

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

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.


TikTok Ads table reference

Replication Method :

Key-based Incremental

Replication Key :

modify_time

Primary Key :

adgroup_id : advertiser_id : campaign_id : modify_time

Official docs :

Official Docs

actions
ARRAY

action_category_ids
ARRAY

items
STRING

adgroups (table), action_category_ids (attribute)

action_period
NUMBER

action_scene
STRING

video_user_actions
ARRAY

items
STRING

adgroups (table), video_user_actions (attribute)
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

items
STRING

adgroups (table), age_groups (attribute)

app_download_url
STRING

app_id
STRING

audience
ARRAY

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

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

items
INTEGER

adgroups (table), device_models (attribute)

device_price_ranges
ARRAY

items
NUMBER

adgroups (table), device_price_ranges (attribute)

excluded_audience
ARRAY

items
INTEGER

adgroups (table), excluded_audience (attribute)

excluded_custom_actions
ARRAY

code
STRING

days
INTEGER

adgroups (table), excluded_custom_actions (attribute)

frequency
INTEGER

frequency_schedule
INTEGER

gender
STRING

included_custom_actions
ARRAY

code
STRING

days
INTEGER

adgroups (table), included_custom_actions (attribute)

interest_category_v2
ARRAY

items
INTEGER

adgroups (table), interest_category_v2 (attribute)

interest_keywords
ARRAY

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

items
STRING

adgroups (table), languages (attribute)

location
ARRAY

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

items
STRING

adgroups (table), network_types (attribute)

next_day_retention
NUMBER

operating_systems
ARRAY

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

items
INTEGER

adgroups (table), pangle_audience_package_exclude (attribute)

pangle_audience_package_include
ARRAY

items
INTEGER

adgroups (table), pangle_audience_package_include (attribute)

pangle_block_app_list_id
ARRAY

items
INTEGER

adgroups (table), pangle_block_app_list_id (attribute)

pixel_id
STRING

placement_type
STRING

placements
ARRAY

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

expansion_types
ARRAY

items
STRING

adgroups (table), expansion_types (attribute)

expansion_enabled
BOOLEAN

adgroups (table), targeting_expansion (attribute)

video_download
STRING


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

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

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

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

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

items
STRING

ads (table), tracking_offline_event_set_ids (attribute)

utm_params
ARRAY

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


Replication Method :

Key-based Incremental

Replication Key :

create_time

Primary Key :

advertiser_id : create_time

Official docs :

Official Docs

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


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

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

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

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


Replication Method :

Key-based Incremental

Replication Key :

modify_time

Primary Key :

advertiser_id : campaign_id : modify_time

Official docs :

Official Docs

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

items
STRING

campaigns (table), special_industries (attribute)

campaign_insights_by_province

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

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.