TikTok Ads connector reference

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

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:

Tables that support incremental updates

The following prebuilt 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

Tables that support batch updates only (non-incremental)

The following tables are refreshed on each pipeline update:

• campaign
• adgroup
• ad
• campaign_report_lifetime
• adgroup_report_lifetime
• ad_report_lifetime

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	CAMPAIGN	BASIC
campaign_report_hourly	campaign_id, stat_time_hour	CAMPAIGN	BASIC
campaign_report_lifetime	campaign_id	CAMPAIGN	BASIC
adgroup_report_daily	adgroup_id, stat_time_day	ADGROUP	BASIC
adgroup_report_hourly	adgroup_id, stat_time_hour	ADGROUP	BASIC
adgroup_report_lifetime	adgroup_id	ADGROUP	BASIC
ad_report_daily	ad_id, stat_time_day	AD	BASIC
ad_report_hourly	ad_id, stat_time_hour	AD	BASIC
ad_report_lifetime	ad_id	AD	BASIC
campaign_age_gender_report	campaign_id, stat_time_day, age, gender	CAMPAIGN	AUDIENCE
campaign_country_report	campaign_id, stat_time_day, country_code	CAMPAIGN	AUDIENCE
campaign_language_report	campaign_id, stat_time_day, language	CAMPAIGN	AUDIENCE
campaign_platform_report	campaign_id, stat_time_day, platform	CAMPAIGN	AUDIENCE
ad_age_gender_report	ad_id, stat_time_day, age, gender	AD	AUDIENCE
ad_country_report	ad_id, stat_time_day, country_code	AD	AUDIENCE
ad_language_report	ad_id, stat_time_day, language	AD	AUDIENCE
ad_platform_report	ad_id, stat_time_day, platform	AD	AUDIENCE

Report (source_table)	Dimensions	Data level	Report type
campaign_report_daily	campaign_id, stat_time_day	CAMPAIGN	BASIC
campaign_report_hourly	campaign_id, stat_time_hour	CAMPAIGN	BASIC
campaign_report_lifetime	campaign_id	CAMPAIGN	BASIC
adgroup_report_daily	adgroup_id, stat_time_day	ADGROUP	BASIC
adgroup_report_hourly	adgroup_id, stat_time_hour	ADGROUP	BASIC
adgroup_report_lifetime	adgroup_id	ADGROUP	BASIC
ad_report_daily	ad_id, stat_time_day	AD	BASIC
ad_report_hourly	ad_id, stat_time_hour	AD	BASIC
ad_report_lifetime	ad_id	AD	BASIC
campaign_age_gender_report	campaign_id, stat_time_day, age, gender	CAMPAIGN	AUDIENCE
campaign_country_report	campaign_id, stat_time_day, country_code	CAMPAIGN	AUDIENCE
campaign_language_report	campaign_id, stat_time_day, language	CAMPAIGN	AUDIENCE
campaign_platform_report	campaign_id, stat_time_day, platform	CAMPAIGN	AUDIENCE
ad_age_gender_report	ad_id, stat_time_day, age, gender	AD	AUDIENCE
ad_country_report	ad_id, stat_time_day, country_code	AD	AUDIENCE
ad_language_report	ad_id, stat_time_day, language	AD	AUDIENCE
ad_platform_report	ad_id, stat_time_day, platform	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
Attribution	conversion, cost_per_conversion, conversion_rate, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate
In-app events	app_install, cost_per_app_install, registration, purchase, cost_per_purchase

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
Attribution	conversion, cost_per_conversion, conversion_rate, real_time_conversion, real_time_cost_per_conversion, real_time_conversion_rate
In-app events	app_install, cost_per_app_install, registration, purchase, cost_per_purchase

AUDIENCE reports return the following metrics:

Group	Metrics
Core performance	spend, impressions, clicks, cpm, cpc, ctr, conversion, cost_per_conversion, conversion_rate, result, result_rate, cost_per_result, reach, frequency
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, result, result_rate, cost_per_result, reach, frequency
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.

destination_table is required when source_table is custom_report.