TikTok Ads Supported Endpoints and Fields
This page lists the TikTok Ads endpoints and fields in the connector. Use it to choose an
endpoint and fields. Each endpoint lists its destination table, unique keys, and TikTok
reference. The connector requests TikTok Business API version v1.3.
Which Endpoint Should I Choose?
Section titled “Which Endpoint Should I Choose?”- For performance reporting such as spend, impressions, clicks, and conversions, start with Ad Performance.
- For performance split by country, use Ad Performance by Country.
- For advertiser account settings, name, and currency, use Advertiser Account.
- For campaign objectives, budgets, and schedules, use Campaigns.
- For bid strategy, optimization goal, placement, and targeting, use Ad Groups.
- For ad names, formats, statuses, and their campaign links, use Ads.
- For custom audience type, size, and expiration, use Custom Audiences.
Supported Endpoints
Section titled “Supported Endpoints”| Endpoint | Use it for | Fields | Unique keys | Destination table |
|---|---|---|---|---|
Advertiser Account (advertiser) | Advertiser account — name, company, and currency. | 4 | advertiser_id | tiktok_ads_advertiser |
Campaigns (campaigns) | Your campaigns — objective, type, status, budget, and schedule. | 34 | campaign_id | tiktok_ads_campaigns |
Ad Groups (ad_groups) | Ad groups within your campaigns — bid strategy, optimization goal, placement, and targeting schedule. | 45 | adgroup_id | tiktok_ads_ad_groups |
Ads (ads) | Individual ads — creative type, format, call to action, status, and links to their campaigns and ad groups. | 46 | ad_id | tiktok_ads_ads |
Custom Audiences (audiences) | Custom audiences — type, size, validity status, and expiration. | 9 | audience_id | tiktok_ads_audiences |
Ad Performance (ad_insights) | Daily ad performance — impressions, clicks, spend, conversions, video views, and engagement. | 39 | Varies by Data Level | tiktok_ads_ad_insights |
Ad Performance by Country (ad_insights_by_country) | Daily ad performance broken down by country — impressions, clicks, spend, conversions, and video views. | 40 | Varies by Data Level | tiktok_ads_ad_insights_by_country |
Data Level and Unique Keys
Section titled “Data Level and Unique Keys”Data Level sets the reporting grain for the two performance endpoints. Choose it before you select fields. The field selector pins the matching unique-key fields, so rows merge correctly.
| Data Level | ad_insights unique keys | ad_insights_by_country unique keys |
|---|---|---|
AUCTION_ADVERTISER | stat_time_day, advertiser_id | stat_time_day, country_code, advertiser_id |
AUCTION_CAMPAIGN | campaign_id, stat_time_day, advertiser_id | campaign_id, stat_time_day, country_code, advertiser_id |
AUCTION_ADGROUP | adgroup_id, stat_time_day, advertiser_id | adgroup_id, stat_time_day, country_code, advertiser_id |
AUCTION_AD | ad_id, stat_time_day, advertiser_id | ad_id, stat_time_day, country_code, advertiser_id |
advertiser_id is always a unique key. Advertiser IDs can list several advertisers
that write into one destination table. At AUCTION_ADVERTISER no other field tells their
rows apart.
⚠️ Do not change Data Level after a run has loaded data into a table. New rows would merge on a different key structure. Use a new Data Mart or a new destination table instead.
Field Table Notes
Section titled “Field Table Notes”- Connector field: the field name in OWOX Data Marts. The connector writes it to the destination table.
- Data type: the type the connector uses in the destination schema.
- Required:
Yes (unique key)means the connector always requests the field, and the selector pins it. On performance endpoints, some fields are required only at certain Data Levels. - Fields marked Required cannot be removed. A run fails with
Missing required unique fieldsif one is missing.
Endpoint Fields
Section titled “Endpoint Fields”Advertiser Account (advertiser)
Section titled “Advertiser Account (advertiser)”Advertiser account — name, company, and currency.
Official TikTok reference: Advertiser Account
Destination table: tiktok_ads_advertiser
Unique keys: advertiser_id
Fields: 4. Selected by default: advertiser_name, currency.
| Connector field | Data type | Required | Description |
|---|---|---|---|
advertiser_id | STRING | Yes (unique key) | Advertiser ID |
advertiser_name | STRING | No | Advertiser Name |
company_name | STRING | No | Company Name |
currency | STRING | No | Account Currency |
Campaigns (campaigns)
Section titled “Campaigns (campaigns)”Your campaigns — objective, type, status, budget, and schedule.
Official TikTok reference: Campaigns
Destination table: tiktok_ads_campaigns
Unique keys: campaign_id
Fields: 34. Selected by default: campaign_name, advertiser_id, objective_type, campaign_type, operation_status, secondary_status, budget_mode, budget, create_time, modify_time.
| Connector field | Data type | Required | Description |
|---|---|---|---|
advertiser_id | STRING | No | Advertiser ID |
campaign_id | STRING | Yes (unique key) | Campaign ID |
campaign_name | STRING | No | Campaign Name |
app_promotion_type | STRING | No | Type of app promotion being used in the campaign |
operation_status | STRING | No | Operation Status |
bid_type | STRING | No | Type of bid strategy being used in the campaign |
roas_bid | NUMBER | No | Return on ad spend bid target |
is_advanced_dedicated_campaign | BOOLEAN | No | Flag indicating if this is an advanced dedicated campaign |
is_search_campaign | BOOLEAN | No | Flag indicating if the campaign is for search ads |
rf_campaign_type | STRING | No | Reach and frequency campaign type |
rta_bid_enabled | BOOLEAN | No | Flag indicating if RTA bidding is enabled |
secondary_status | STRING | No | Additional status information of the campaign |
postback_window_mode | STRING | No | Mode for the postback window |
disable_skan_campaign | BOOLEAN | No | Flag indicating if SKAdNetwork is disabled for the campaign |
budget_optimize_on | BOOLEAN | No | The metric or event that the budget optimization is based on |
budget_mode | STRING | No | Budget Mode (BUDGET_MODE_DAY or BUDGET_MODE_TOTAL) |
objective | STRING | No | Campaign Objective |
campaign_product_source | STRING | No | Source of products for the campaign |
optimization_goal | STRING | No | Specific goal to be optimized for in the campaign |
special_industries | STRING | No | Special industries classification for the campaign |
deep_bid_type | STRING | No | Type of deep bidding strategy |
rta_id | STRING | No | Real-time advertising ID |
rta_product_selection_enabled | BOOLEAN | No | Flag indicating if RTA product selection is enabled |
budget | NUMBER | No | Campaign Budget |
is_new_structure | BOOLEAN | No | Flag indicating if the campaign utilizes a new campaign structure |
is_smart_performance_campaign | BOOLEAN | No | Flag indicating if the campaign uses smart performance optimization |
modify_time | DATETIME | No | Last Modified Time |
app_id | STRING | No | ID of the app being promoted |
objective_type | STRING | No | Type of objective selected for the campaign (e.g., brand awareness, app installs) |
campaign_type | STRING | No | Type of campaign (e.g., awareness, conversion) |
campaign_app_profile_page_state | STRING | No | App profile page state for app campaigns |
create_time | DATETIME | No | Creation Time |
catalog_enabled | BOOLEAN | No | Flag indicating if product catalog is enabled |
bid_align_type | STRING | No | Type of bid alignment |
Ad Groups (ad_groups)
Section titled “Ad Groups (ad_groups)”Ad groups within your campaigns — bid strategy, optimization goal, placement, and targeting schedule.
Official TikTok reference: Ad Groups
Destination table: tiktok_ads_ad_groups
Unique keys: adgroup_id
Fields: 45. Selected by default: adgroup_name, advertiser_id, campaign_id, campaign_name, operation_status, budget_mode, budget, bid_type, optimization_goal, placement_type, schedule_start_time, schedule_end_time, create_time, modify_time.
| Connector field | Data type | Required | Description |
|---|---|---|---|
adgroup_id | STRING | Yes (unique key) | Ad Group ID |
adgroup_name | STRING | No | Ad Group Name |
advertiser_id | STRING | No | Advertiser ID |
campaign_id | STRING | No | Campaign ID |
campaign_name | STRING | No | Campaign Name |
operation_status | STRING | No | Operation Status |
budget | NUMBER | No | Ad Group Budget |
budget_mode | STRING | No | Budget Mode (BUDGET_MODE_DAY or BUDGET_MODE_TOTAL) |
bid_type | STRING | No | Bidding Type |
bid_price | NUMBER | No | Bid Price |
optimization_goal | STRING | No | Optimization Goal |
optimization_event | STRING | No | Optimization Event |
app_id | STRING | No | ID of the app being promoted |
app_type | STRING | No | Type of app |
audience_type | STRING | No | Type of audience |
audience_ids | ARRAY | No | List of audience IDs |
excluded_audience_ids | ARRAY | No | List of excluded audience IDs |
gender | STRING | No | Target gender |
age_groups | ARRAY | No | Target age groups |
languages | ARRAY | No | Target languages |
location_ids | ARRAY | No | Target location IDs |
interest_category_ids | ARRAY | No | Interest category IDs |
placements | ARRAY | No | Ad placements |
placement_type | STRING | No | Type of placement |
schedule_start_time | DATETIME | No | Schedule Start Time |
schedule_end_time | DATETIME | No | Schedule End Time |
schedule_type | STRING | No | Type of schedule |
frequency | INTEGER | No | Frequency cap |
billing_event | STRING | No | Billing Event Type |
conversion_id | STRING | No | Conversion ID |
conversion_bid_price | NUMBER | No | Conversion Bid Price |
conversion_window | INTEGER | No | Conversion Window |
click_attribution_window | INTEGER | No | Click Attribution Window |
view_attribution_window | INTEGER | No | View Attribution Window |
is_smart_performance_campaign | BOOLEAN | No | Flag indicating if the ad group uses smart performance optimization |
is_new_structure | BOOLEAN | No | Flag indicating if the ad group utilizes a new structure |
auto_targeting_enabled | BOOLEAN | No | Flag indicating if auto targeting is enabled |
targeting_expansion | OBJECT | No | Targeting expansion settings |
device_price_ranges | ARRAY | No | Target device price ranges |
device_model_ids | ARRAY | No | Target device model IDs |
operating_systems | ARRAY | No | Target operating systems |
network_types | ARRAY | No | Target network types |
carrier_ids | ARRAY | No | Target carrier IDs |
create_time | DATETIME | No | Creation Time |
modify_time | DATETIME | No | Last Modified Time |
Ads (ads)
Section titled “Ads (ads)”Individual ads — creative type, format, call to action, status, and links to their campaigns and ad groups.
Official TikTok reference: Ads
Destination table: tiktok_ads_ads
Unique keys: ad_id
Fields: 46. Selected by default: ad_name, advertiser_id, campaign_id, campaign_name, adgroup_id, adgroup_name.
| Connector field | Data type | Required | Description |
|---|---|---|---|
ad_id | STRING | Yes (unique key) | Ad ID |
ad_name | STRING | No | Ad Name |
advertiser_id | STRING | No | Advertiser ID |
campaign_id | STRING | No | Campaign ID |
campaign_name | STRING | No | Campaign Name |
adgroup_id | STRING | No | Ad Group ID |
adgroup_name | STRING | No | Ad Group Name |
operation_status | STRING | No | Operation Status |
secondary_status | STRING | No | Secondary Status |
create_time | DATETIME | No | Creation Time |
modify_time | DATETIME | No | Last Modified Time |
ad_text | STRING | No | Ad Text/Caption |
ad_texts | ARRAY | No | Multiple Ad Text Variations |
call_to_action | STRING | No | Call To Action Text |
call_to_action_id | STRING | No | Call To Action ID |
image_ids | ARRAY | No | Image IDs Used in the Ad |
video_id | STRING | No | Video ID Used in the Ad |
image_mode | STRING | No | Image Display Mode |
creative_type | STRING | No | Type of Creative (video, image, etc.) |
ad_format | STRING | No | Format of the Ad |
landing_page_url | STRING | No | Landing Page URL |
landing_page_urls | ARRAY | No | Multiple Landing Page URLs |
deeplink | STRING | No | Deep Link URL |
deeplink_type | STRING | No | Type of Deep Link |
tracking_pixel_id | STRING | No | Pixel ID for Tracking |
impression_tracking_url | STRING | No | URL for Impression Tracking |
click_tracking_url | STRING | No | URL for Click Tracking |
video_view_tracking_url | STRING | No | URL for Video View Tracking |
is_new_structure | BOOLEAN | No | Flag indicating new ad structure |
is_aco | BOOLEAN | No | Flag indicating Automated Creative Opt. |
optimization_event | STRING | No | Event being optimized for |
catalog_id | STRING | No | Product Catalog ID |
product_set_id | STRING | No | Product Set ID |
sku_ids | ARRAY | No | SKU IDs for Products |
domain | STRING | No | Domain for the Ad |
display_name | STRING | No | Display Name shown in the Ad |
profile_image_url | STRING | No | URL for Profile Image |
app_name | STRING | No | Name of the App being promoted |
tracking_app_id | STRING | No | App ID for Tracking |
identity_id | STRING | No | Identity ID |
identity_type | STRING | No | Type of Identity |
page_id | STRING | No | TikTok Page ID |
tiktok_item_id | STRING | No | TikTok Item ID |
disclaimer_type | STRING | No | Type of Disclaimer |
disclaimer_text | STRING | No | Disclaimer Text |
utm_params | OBJECT | No | UTM Parameters |
Custom Audiences (audiences)
Section titled “Custom Audiences (audiences)”Custom audiences — type, size, validity status, and expiration.
Official TikTok reference: Custom Audiences
Destination table: tiktok_ads_audiences
Unique keys: audience_id
Fields: 9. Selected by default: advertiser_id, name, audience_type, cover_num, is_valid, is_expiring, create_time.
| Connector field | Data type | Required | Description |
|---|---|---|---|
audience_id | STRING | Yes (unique key) | Unique identifier for the audience |
advertiser_id | STRING | No | Advertiser ID |
name | STRING | No | Name of the audience |
audience_type | STRING | No | Type of audience (e.g., demographic, interest-based) |
cover_num | INTEGER | No | Number of audience members covered |
create_time | DATETIME | No | Timestamp indicating when the audience was created |
is_valid | BOOLEAN | No | Flag indicating if the audience data is valid |
is_expiring | BOOLEAN | No | Flag indicating if the audience data is expiring soon |
expired_time | DATETIME | No | Timestamp indicating when the audience data expires |
Ad Performance (ad_insights)
Section titled “Ad Performance (ad_insights)”Daily ad performance — impressions, clicks, spend, conversions, video views, and engagement.
Official TikTok reference: Ad Performance
Destination table: tiktok_ads_ad_insights
Unique keys depend on Data Level:
| Data Level | Unique keys |
|---|---|
AUCTION_ADVERTISER | stat_time_day, advertiser_id |
AUCTION_CAMPAIGN | campaign_id, stat_time_day, advertiser_id |
AUCTION_ADGROUP | adgroup_id, stat_time_day, advertiser_id |
AUCTION_AD | ad_id, stat_time_day, advertiser_id |
BigQuery partition field: stat_time_day
Fields: 39. Selected by default: advertiser_id, date_start, date_end, impressions, clicks, spend.
| Connector field | Data type | Required | Description |
|---|---|---|---|
ad_id | STRING | Yes at AUCTION_AD | Ad ID |
advertiser_id | STRING | Yes (unique key) | Advertiser ID |
campaign_id | STRING | Yes at AUCTION_CAMPAIGN | Campaign ID |
adgroup_id | STRING | Yes at AUCTION_ADGROUP | Ad Group ID |
stat_time_day | DATE | Yes (unique key) | Statistics Date |
date_start | DATE | No | Start Date |
date_end | DATE | No | End Date |
impressions | INTEGER | No | Impressions |
clicks | INTEGER | No | Clicks |
cost | NUMBER | No | Cost |
ctr | NUMBER | No | Click-Through Rate |
conversion | INTEGER | No | Conversions |
cost_per_conversion | NUMBER | No | Cost Per Conversion |
conversion_rate | NUMBER | No | Conversion Rate |
reach | INTEGER | No | Reach |
engagement | INTEGER | No | Engagement |
video_views | INTEGER | No | Video Views |
video_watched_2s | INTEGER | No | 2s Video Views |
video_watched_6s | INTEGER | No | 6s Video Views |
video_completion | INTEGER | No | Video Completion |
spend | NUMBER | No | Spend |
cpc | NUMBER | No | Cost per click |
cpm | NUMBER | No | Cost per thousand impressions |
frequency | NUMBER | No | Frequency of occurrence |
video_play_actions | INTEGER | No | Number of video plays |
video_views_p25 | INTEGER | No | Video views at 25% completion |
video_views_p50 | INTEGER | No | Video views at 50% completion |
video_views_p75 | INTEGER | No | Video views at 75% completion |
video_views_p100 | INTEGER | No | Video views at 100% completion |
profile_visits | INTEGER | No | Profile visits |
likes | INTEGER | No | Likes count |
comments | INTEGER | No | Comments count |
shares | INTEGER | No | Shares count |
follows | INTEGER | No | Follows count |
real_time_conversion | INTEGER | No | Real-time conversions |
real_time_cost_per_conversion | NUMBER | No | Cost per conversion in real-time |
real_time_conversion_rate | NUMBER | No | Real-time conversion rate |
result | INTEGER | No | Number of results |
cost_per_result | NUMBER | No | Cost per result |
Ad Performance by Country (ad_insights_by_country)
Section titled “Ad Performance by Country (ad_insights_by_country)”Daily ad performance broken down by country — impressions, clicks, spend, conversions, and video views.
Official TikTok reference: Ad Performance by Country
Destination table: tiktok_ads_ad_insights_by_country
Unique keys depend on Data Level:
| Data Level | Unique keys |
|---|---|
AUCTION_ADVERTISER | stat_time_day, country_code, advertiser_id |
AUCTION_CAMPAIGN | campaign_id, stat_time_day, country_code, advertiser_id |
AUCTION_ADGROUP | adgroup_id, stat_time_day, country_code, advertiser_id |
AUCTION_AD | ad_id, stat_time_day, country_code, advertiser_id |
BigQuery partition field: stat_time_day
Fields: 40. Selected by default: advertiser_id, date_start, date_end, impressions, clicks, spend.
| Connector field | Data type | Required | Description |
|---|---|---|---|
ad_id | STRING | Yes at AUCTION_AD | Ad ID |
advertiser_id | STRING | Yes (unique key) | Advertiser ID |
campaign_id | STRING | Yes at AUCTION_CAMPAIGN | Campaign ID |
adgroup_id | STRING | Yes at AUCTION_ADGROUP | Ad Group ID |
country_code | STRING | Yes (unique key) | Two-letter ISO country code (geographic breakdown dimension) |
stat_time_day | DATE | Yes (unique key) | Statistics Date |
date_start | DATE | No | Start Date |
date_end | DATE | No | End Date |
impressions | INTEGER | No | Impressions |
clicks | INTEGER | No | Clicks |
cost | NUMBER | No | Cost |
ctr | NUMBER | No | Click-Through Rate |
conversion | INTEGER | No | Conversions |
cost_per_conversion | NUMBER | No | Cost Per Conversion |
conversion_rate | NUMBER | No | Conversion Rate |
reach | INTEGER | No | Reach |
engagement | INTEGER | No | Engagement |
video_views | INTEGER | No | Video Views |
video_watched_2s | INTEGER | No | 2s Video Views |
video_watched_6s | INTEGER | No | 6s Video Views |
video_completion | INTEGER | No | Video Completion |
spend | NUMBER | No | Spend |
cpc | NUMBER | No | Cost per click |
cpm | NUMBER | No | Cost per thousand impressions |
frequency | NUMBER | No | Frequency of occurrence |
video_play_actions | INTEGER | No | Number of video plays |
video_views_p25 | INTEGER | No | Video views at 25% completion |
video_views_p50 | INTEGER | No | Video views at 50% completion |
video_views_p75 | INTEGER | No | Video views at 75% completion |
video_views_p100 | INTEGER | No | Video views at 100% completion |
profile_visits | INTEGER | No | Profile visits |
likes | INTEGER | No | Likes count |
comments | INTEGER | No | Comments count |
shares | INTEGER | No | Shares count |
follows | INTEGER | No | Follows count |
real_time_conversion | INTEGER | No | Real-time conversions |
real_time_cost_per_conversion | NUMBER | No | Cost per conversion in real-time |
real_time_conversion_rate | NUMBER | No | Real-time conversion rate |
result | INTEGER | No | Number of results |
cost_per_result | NUMBER | No | Cost per result |