TikTok Ads connector reference
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_dailycampaign_report_hourlyadgroup_report_dailyadgroup_report_hourlyad_report_dailyad_report_hourlycampaign_age_gender_reportcampaign_country_reportcampaign_language_reportcampaign_platform_reportad_age_gender_reportad_country_reportad_language_reportad_platform_reportcustom_reportwhenquery_lifetimeisfalse
Tables that support batch updates only (non-incremental)
The following tables are refreshed on each pipeline update:
campaignad_groupadbusiness_centercampaign_report_lifetimeadgroup_report_lifetimead_report_lifetimecustom_reportwhenquery_lifetimeistrue
Prebuilt reports
Prebuilt reports are pre-configured report queries with fixed dimensions and metrics for common reporting needs.
Report ( | Dimensions | Data level | Report type |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Metric groups
The metrics returned for each prebuilt report depend on its report type.
BASIC reports return the following metrics:
Group | Metrics |
|---|---|
Core performance |
|
Video play |
|
Engagement |
|
Attribution |
|
In-app events |
|
Page events |
|
TikTok Shop events |
|
SKAdNetwork (SKAN) |
|
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 |
|
Page events |
|
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.
{
"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 |
|---|---|
| List of dimensions to include (for example, |
| List of metric fields to return. |
| Report type: |
| Aggregation level: |
| If |
Custom reports have the following requirements:
- Set
destination_tablewhensource_tableiscustom_report. Custom reports aren't returned by table discovery and must be configured explicitly. - Provide at least one value for both
dimensionsandmetrics. - For a non-lifetime report, include either
stat_time_dayorstat_time_hourindimensions. - A lifetime custom report is fully refreshed on each pipeline update. Don't configure
sync_start_dateorlookback_window_daysfor a lifetime report.
Report date options
You can configure the following options under connector_options.tiktok_ads_options for non-lifetime reports:
Field | Description |
|---|---|
| The initial date to ingest, in |
| The number of recent days to reread during incremental updates, from |
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.