Skip to main content

TikTok Ads connector reference

Beta

This feature is in Beta.

This article provides reference information for the TikTok Ads connector, including supported tables, dimensions, and metrics.

Supported source tables​

The TikTok Ads connector supports the following source tables:

For advertiser-scoped tables, set source_schema to the TikTok advertiser ID. For business_center, set source_schema to default.

Tables that support incremental updates​

The following report tables support incremental ingestion:

  • campaign_report_daily
  • campaign_report_hourly
  • adgroup_report_daily
  • adgroup_report_hourly
  • ad_report_daily
  • ad_report_hourly
  • campaign_age_gender_report
  • campaign_country_report
  • campaign_language_report
  • campaign_platform_report
  • ad_age_gender_report
  • ad_country_report
  • ad_language_report
  • ad_platform_report
  • custom_report when query_lifetime is false

Tables that support batch updates only (non-incremental)​

The following tables are refreshed on each pipeline update:

  • campaign
  • ad_group
  • ad
  • business_center
  • campaign_report_lifetime
  • adgroup_report_lifetime
  • ad_report_lifetime
  • custom_report when query_lifetime is true

Prebuilt reports​

Prebuilt reports are pre-configured report queries with fixed dimensions and metrics for common reporting needs.

Report (source_table)

Dimensions

Data level

Report type

campaign_report_daily

campaign_id, stat_time_day

AUCTION_CAMPAIGN

BASIC

campaign_report_hourly

campaign_id, stat_time_hour

AUCTION_CAMPAIGN

BASIC

campaign_report_lifetime

campaign_id

AUCTION_CAMPAIGN

BASIC

adgroup_report_daily

adgroup_id, stat_time_day

AUCTION_ADGROUP

BASIC

adgroup_report_hourly

adgroup_id, stat_time_hour

AUCTION_ADGROUP

BASIC

adgroup_report_lifetime

adgroup_id

AUCTION_ADGROUP

BASIC

ad_report_daily

ad_id, stat_time_day

AUCTION_AD

BASIC

ad_report_hourly

ad_id, stat_time_hour

AUCTION_AD

BASIC

ad_report_lifetime

ad_id

AUCTION_AD

BASIC

campaign_age_gender_report

campaign_id, stat_time_day, age, gender

AUCTION_CAMPAIGN

AUDIENCE

campaign_country_report

campaign_id, stat_time_day, country_code

AUCTION_CAMPAIGN

AUDIENCE

campaign_language_report

campaign_id, stat_time_day, language

AUCTION_CAMPAIGN

AUDIENCE

campaign_platform_report

campaign_id, stat_time_day, platform

AUCTION_CAMPAIGN

AUDIENCE

ad_age_gender_report

ad_id, stat_time_day, age, gender

AUCTION_AD

AUDIENCE

ad_country_report

ad_id, stat_time_day, country_code

AUCTION_AD

AUDIENCE

ad_language_report

ad_id, stat_time_day, language

AUCTION_AD

AUDIENCE

ad_platform_report

ad_id, stat_time_day, platform

AUCTION_AD

AUDIENCE

Report (source_table)

Dimensions

Data level

Report type

campaign_report_daily

campaign_id, stat_time_day

AUCTION_CAMPAIGN

BASIC

campaign_report_hourly

campaign_id, stat_time_hour

AUCTION_CAMPAIGN

BASIC

campaign_report_lifetime

campaign_id

AUCTION_CAMPAIGN

BASIC

adgroup_report_daily

adgroup_id, stat_time_day

AUCTION_ADGROUP

BASIC

adgroup_report_hourly

adgroup_id, stat_time_hour

AUCTION_ADGROUP

BASIC

adgroup_report_lifetime

adgroup_id

AUCTION_ADGROUP

BASIC

ad_report_daily

ad_id, stat_time_day

AUCTION_AD

BASIC

ad_report_hourly

ad_id, stat_time_hour

AUCTION_AD

BASIC

ad_report_lifetime

ad_id

AUCTION_AD

BASIC

campaign_age_gender_report

campaign_id, stat_time_day, age, gender

AUCTION_CAMPAIGN

AUDIENCE

campaign_country_report

campaign_id, stat_time_day, country_code

AUCTION_CAMPAIGN

AUDIENCE

campaign_language_report

campaign_id, stat_time_day, language

AUCTION_CAMPAIGN

AUDIENCE

campaign_platform_report

campaign_id, stat_time_day, platform

AUCTION_CAMPAIGN

AUDIENCE

ad_age_gender_report

ad_id, stat_time_day, age, gender

AUCTION_AD

AUDIENCE

ad_country_report

ad_id, stat_time_day, country_code

AUCTION_AD

AUDIENCE

ad_language_report

ad_id, stat_time_day, language

AUCTION_AD

AUDIENCE

ad_platform_report

ad_id, stat_time_day, platform

AUCTION_AD

AUDIENCE

Metric groups​

The metrics returned for each prebuilt report depend on its report type.

BASIC reports return the following metrics:

Group

Metrics

Core performance

spend, impressions, clicks, cpc, cpm, ctr, reach, cost_per_1000_reached, frequency

Video play

video_play_actions, video_watched_2s, video_watched_6s, video_views_p25, video_views_p50, video_views_p75, video_views_p100, average_video_play, average_video_play_per_user

Engagement

likes, comments, shares, follows, profile_visits, profile_visits_rate

Attribution

conversion, cost_per_conversion, conversion_rate, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate, total_complete_payment_rate

In-app events

app_install, cost_per_app_install, registration, cost_per_registration, purchase, cost_per_purchase, app_event_add_to_cart, cost_per_app_event_add_to_cart, checkout, cost_per_checkout

Page events

page_event_search, cost_per_page_event_search, complete_payment, cost_per_complete_payment

TikTok Shop events

product_details_page_browse, initiate_checkout, live_views, live_product_clicks

SKAdNetwork (SKAN)

skan_conversion, skan_cost_per_conversion, skan_app_install, skan_cost_per_app_install, skan_purchase, skan_cost_per_purchase, skan_registration, skan_cost_per_registration

Group

Metrics

Core performance

spend, impressions, clicks, cpc, cpm, ctr, reach, cost_per_1000_reached, frequency

Video play

video_play_actions, video_watched_2s, video_watched_6s, video_views_p25, video_views_p50, video_views_p75, video_views_p100, average_video_play, average_video_play_per_user

Engagement

likes, comments, shares, follows, profile_visits, profile_visits_rate

Attribution

conversion, cost_per_conversion, conversion_rate, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate, total_complete_payment_rate

In-app events

app_install, cost_per_app_install, registration, cost_per_registration, purchase, cost_per_purchase, app_event_add_to_cart, cost_per_app_event_add_to_cart, checkout, cost_per_checkout

Page events

page_event_search, cost_per_page_event_search, complete_payment, cost_per_complete_payment

TikTok Shop events

product_details_page_browse, initiate_checkout, live_views, live_product_clicks

SKAdNetwork (SKAN)

skan_conversion, skan_cost_per_conversion, skan_app_install, skan_cost_per_app_install, skan_purchase, skan_cost_per_purchase, skan_registration, skan_cost_per_registration

SKAdNetwork (SKAN) metrics are returned for daily and lifetime BASIC reports, but not for hourly reports.

AUDIENCE reports return the following metrics:

Group

Metrics

Core performance

spend, impressions, clicks, cpm, cpc, ctr, conversion, cost_per_conversion, conversion_rate, conversion_rate_v2, frequency, reach, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate, real_time_conversion_rate_v2, result, result_rate, cost_per_result, real_time_result, real_time_cost_per_result, real_time_result_rate

Page events

total_landing_page_view, cost_per_landing_page_view, landing_page_view_rate

Group

Metrics

Core performance

spend, impressions, clicks, cpm, cpc, ctr, conversion, cost_per_conversion, conversion_rate, conversion_rate_v2, frequency, reach, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate, real_time_conversion_rate_v2, result, result_rate, cost_per_result, real_time_result, real_time_cost_per_result, real_time_result_rate

Page events

total_landing_page_view, cost_per_landing_page_view, landing_page_view_rate

Custom reports​

In addition to prebuilt reports, you can create custom reports by setting source_table to custom_report in your pipeline spec and providing custom_report_options under connector_options.tiktok_ads_options.

JSON
{
"table": {
"source_schema": "<your-ad-account-id>",
"source_table": "custom_report",
"destination_catalog": "<destination-catalog>",
"destination_schema": "<destination-schema>",
"destination_table": "<your-report-name>",
"connector_options": {
"tiktok_ads_options": {
"lookback_window_days": 7,
"sync_start_date": "<YYYY-MM-DD>",
"custom_report_options": {
"dimensions": ["stat_time_day", "ad_id"],
"metrics": ["spend", "impressions", "clicks"],
"report_type": "BASIC",
"data_level": "AUCTION_AD",
"query_lifetime": false
}
}
}
}
}

custom_report_options fields​

Field

Description

dimensions

List of dimensions to include (for example, ["stat_time_day", "ad_id"]).

metrics

List of metric fields to return.

report_type

Report type: BASIC or AUDIENCE.

data_level

Aggregation level: AUCTION_CAMPAIGN, AUCTION_ADGROUP, or AUCTION_AD.

query_lifetime

If true, returns lifetime totals with no date range. Defaults to false.

Field

Description

dimensions

List of dimensions to include (for example, ["stat_time_day", "ad_id"]).

metrics

List of metric fields to return.

report_type

Report type: BASIC or AUDIENCE.

data_level

Aggregation level: AUCTION_CAMPAIGN, AUCTION_ADGROUP, or AUCTION_AD.

query_lifetime

If true, returns lifetime totals with no date range. Defaults to false.

Custom reports have the following requirements:

  • Set destination_table when source_table is custom_report. Custom reports aren't returned by table discovery and must be configured explicitly.
  • Provide at least one value for both dimensions and metrics.
  • For a non-lifetime report, include either stat_time_day or stat_time_hour in dimensions.
  • A lifetime custom report is fully refreshed on each pipeline update. Don't configure sync_start_date or lookback_window_days for a lifetime report.

Report date options​

You can configure the following options under connector_options.tiktok_ads_options for non-lifetime reports:

Field

Description

sync_start_date

The initial date to ingest, in YYYY-MM-DD format. The date can't be in the future. This option affects only the initial sync. If omitted, daily and audience reports ingest the previous 730 days and hourly reports ingest the previous 365 days.

lookback_window_days

The number of recent days to reread during incremental updates, from 7 through 365. The default is 7. Rereading this window captures delayed attribution and updated metrics.

Field

Description

sync_start_date

The initial date to ingest, in YYYY-MM-DD format. The date can't be in the future. This option affects only the initial sync. If omitted, daily and audience reports ingest the previous 730 days and hourly reports ingest the previous 365 days.

lookback_window_days

The number of recent days to reread during incremental updates, from 7 through 365. The default is 7. Rereading this window captures delayed attribution and updated metrics.

Report dates use the advertiser account's fixed GMT offset. TikTok's advertiser offset doesn't change for daylight saving time, even when the account timezone is represented by a region name.