Import Data from TikTok Ads

Use this guide to create a TikTok Ads Data Mart.

Before You Start

Check these items before you create the Data Mart:

• You have set up OWOX Data Marts.
• You have an OWOX storage, or you create one during setup.
• You can access the target advertiser account in TikTok Ads Manager.
• You know your numeric Advertiser IDs.
• You chose an authentication method in Credentials.

For a general connector walkthrough, see Connector-based Data Mart.

Create the Data Mart

1. Click New Data Mart.
2. Enter a title.
3. Select a storage.
4. Click Create Data Mart.

If you have no storage yet, choose Create new storage in the Storage dropdown, then pick a storage type. You can add its settings later. The Data Mart cannot publish until the storage settings are valid.

Set Up the Connector

1. In Input Source, set Definition Type to Connector.
2. Click Set up connector and choose TikTok Ads.
3. Choose your authentication method.

For OAuth, click Continue with TikTok, then sign in with a TikTok user who can access the advertiser account. If the button does not appear, use the Access Token method.

For manual authentication, fill in these fields:

• Access Token: paste the token from Credentials.
• App ID: enter your TikTok App ID.
• App Secret: enter your TikTok App Secret.

Find the App ID and App Secret in My Apps → App Detail → Basic Information.

In both methods, fill in Advertiser IDs. Use numeric IDs only. To import from several advertisers, separate the IDs with commas or semicolons. You receive these IDs with the access token. You can also find them in TikTok Ads Manager. The authorized TikTok user must access every listed advertiser.

Choose Data Level Before Fields

Data Level sets the reporting grain for ad_insights and ad_insights_by_country. Pick the level you report at; finer levels create more rows. Choose it before you select fields. The field selector pins the matching unique-key fields, so rows merge correctly.

Data Level	Use it for	Pinned fields
AUCTION_AD (default)	Daily metrics per ad.	ad_id, stat_time_day, advertiser_id
AUCTION_ADGROUP	Daily metrics per ad group.	adgroup_id, stat_time_day, advertiser_id
AUCTION_CAMPAIGN	Daily metrics per campaign.	campaign_id, stat_time_day, advertiser_id
AUCTION_ADVERTISER	Advertiser-level daily totals.	stat_time_day, advertiser_id

ad_insights_by_country uses the same grain and adds country_code to the pinned fields.

advertiser_id is always pinned. Advertiser IDs can list several advertisers that write into one destination table. At AUCTION_ADVERTISER no other field tells their rows apart.

Add any metrics you need. The field selector locks the pinned fields, so you cannot clear them.

⚠️ 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.

Configure Data Import

1. Choose an endpoint. Each Data Mart imports one endpoint, so create another Data Mart for each additional endpoint.
2. Select fields, or keep the defaults.
3. Enter the target dataset, or keep the default. The connector names each table after its endpoint, for example tiktok_ads_ad_insights.
4. Click Finish.
5. Click Publish & Run Data Mart. The first run imports from the first day of the previous month and can take several minutes.

The connector writes its tables into your storage. The field label depends on your storage, such as Dataset for BigQuery or Database for Amazon Redshift. For your storage, see Supported Storages.

For spend, impressions, clicks, and conversions, choose Ad Performance (ad_insights). Use Ad Performance by Country (ad_insights_by_country) when you also need a country breakdown.

For endpoint details, see Endpoints and Fields.

Publish & Run Data Mart stays inactive until your storage has valid settings. Open the storage, check its settings, then come back to this step. See Storage Management.

Advanced Settings

Open Advanced settings to reach these options. The defaults suit most imports.

Setting	Default	What it does
Reimport Lookback Window	2	Days to re-request before the last imported date. Refreshes metrics that TikTok updated later.
Include Deleted	Off	Imports deleted campaigns, ad groups, and ads. It does not affect the advertiser, performance, or audience endpoints.
Sandbox Mode	Off	Sends requests to TikTok’s test environment. Use it only to test an integration.
Process Short Links	On	Resolves short links in landing_page_url and landing_page_urls into their _parsed fields. See Resolve Short Links.
Create Empty Tables	On	Creates the destination table with every selected column, even when TikTok returns no rows.

Keep Create Empty Tables on. When you turn it off and TikTok returns no rows, the connector creates no table. Later runs then fail with Not found: Table. See Troubleshooting.

Reimport Lookback Window decides how far back each run re-requests data. For conversion metrics, set it at least as long as your campaigns’ attribution window. Impressions, clicks, and spend settle within a day or two.

Sandbox Mode restricts what you can import. TikTok supplies mock reporting data for 2020-12-08 through 2020-12-19 only. It does not support AUCTION_ADVERTISER, the advertiser endpoint, or the audiences endpoint. See Troubleshooting.

Resolve Short Links

Ads often point to short links. OWOX can follow each short link and store its target next to it:

• Ads: landing_page_url resolves into landing_page_url_parsed, and landing_page_urls into landing_page_urls_parsed.

Keep the source field and its parsed field selected and keep Process Short Links on. OWOX selects landing_page_url and landing_page_url_parsed by default. A parsed field holds the address the short link service points to, and the original value for other links. OWOX does not request that address, so redirects on the landing site itself are not followed.

OWOX resolves links from known short link services, such as Bitly (bit.ly) and TinyURL (tinyurl.com). Links on other domains stay unchanged. Your administrator adds your own short link domains to the CONNECTOR_SHORT_LINK_DOMAINS environment variable. In OWOX Cloud, contact support to add a domain. See Environment Variables.

OWOX sends one request per distinct link and remembers the answer for 30 days, including links that do not redirect. Later runs skip remembered links. If a Data Mart has more distinct links than the memory holds, OWOX requests the extra ones on each run.

OWOX re-imports Ads on every run, so existing rows get the parsed field on the next run.

Start a Manual Run

Publish & Run Data Mart already started the first import. Without a trigger, the Data Mart does not run again. To import again, click Manual Run and choose a run type, or set a trigger. See schedule connector runs.

Schedule Automatic Runs

1. Open the Triggers tab of your Data Mart.
2. Click + Add Trigger.
3. Set Trigger Type to Connector Run.
4. Choose a schedule: Daily, Weekly, Monthly, or Interval.
5. Click Save.

Incremental Load

Choose Manual run → Incremental load.

The first incremental run imports data from the first day of the previous month through today.

Each successful run saves the last requested date. Later runs start from that date minus Reimport Lookback Window. The default window is two days. This lookback refreshes TikTok metrics that changed after the first import.

Backfill

Choose Backfill (custom period) to import a specific date range.

1. Select Start Date.
2. Select End Date.
3. Click Run.

The import includes both the start date and the end date. One backfill run covers at most 31 days, so a full calendar month fits in one run. The form shows how many days your period covers and rejects a longer one before the run starts. To reload a longer history, run several backfills with consecutive periods. Start each run after the previous one finishes.

Both dates are required. The date picker does not offer future dates. The End Date must be on or after the Start Date.

Check the Result

Open Run history. The run has finished when the status shows Success.

A run can finish with warnings. It skips advertisers it cannot reach and keeps every row it fetched. See Warnings and Errors.

You can query the imported tables in the dataset you selected. You can also send the data to a destination. See Destination Management and Google Sheets.

Troubleshooting

If a run fails, open Run history. Then match the error with Troubleshooting.

For credential setup errors, see Credentials.

Support

1. Check Run history for the exact error.
2. Search Q&A.
3. Open an issue to report a bug.
4. Join the discussion forum.