TikTok Ads to BigQuery: How to Move Your Data

Syncing TikTok Ads to BigQuery puts campaign, ad group, and creative performance into a warehouse where it can sit alongside your other paid channels and your actual revenue data. Airbyte's TikTok Marketing connector does the extraction with no code. Before you schedule anything, one number governs how you configure it: the TikTok Reporting API has a data latency of roughly 11 hours.

Metrics for a given day continue changing well after that day ends. A pipeline that reads each day once and moves on will capture a version of the numbers that TikTok itself no longer agrees with.

Why does the attribution window matter so much?

The TikTok Marketing connector exposes an Attribution window setting, defaulting to 3 days with a range from 0 to 364. It controls how far back the connector looks to update metrics on incremental report streams.

Given the roughly 11-hour reporting latency, the documentation recommends using a window of at least 3 days on incremental syncs so the connector captures updated metrics in records it has already written. Setting it to 0 means you read each day once and keep whatever TikTok had at that moment, which for a channel with delayed conversions is close to guaranteed to disagree with the TikTok Ads Manager UI.

A larger window captures more delayed attribution at the cost of re-reading more data on every sync. If your conversion cycle is long, raise it. The trade is straightforwardly between accuracy and sync volume, and accuracy usually wins, because a marketing team that cannot reconcile the warehouse against the platform will stop trusting the warehouse.

Because the same day is read repeatedly, deduplicate on the record key so a restated day replaces the earlier version rather than accumulating alongside it.

Choosing granularity and handling large accounts

Reports can aggregate hourly, daily, or lifetime. Daily gives one row per day for the report duration, with each row carrying that day's impressions and other metrics. Hourly multiplies your row count by 24 and is worth it only if you genuinely analyse intraday performance. Lifetime gives cumulative totals rather than a time series, which is a different shape entirely and rarely what a dashboard wants.

Pick this before the first sync. Changing granularity later changes the meaning of every row already in your table.

There is also a Daily Reports Date Step setting, defaulting to 30 days with a range of 1 to 30, which controls how large a date chunk the connector requests at once. If the TikTok API returns error 40067, meaning the query is too large, the connector surfaces it as a configuration error telling you to reduce this value. Airbyte's documentation notes this typically affects accounts with many ads or ad groups, and suggests dropping the value to 7 or 1 and retrying. If you manage a large account, expect to tune this rather than treating the first failure as a bug.

Which records might be missing?

One behaviour deserves attention because it produces a silent gap. The ads stream uses modify_time as its incremental cursor and skips any record where TikTok does not return that field. TikTok can omit it from Smart+ ad records, which means those ads do not appear in the stream at all.

If you run Smart+ campaigns and your ad-level dimension table looks short against the TikTok UI, this is the first thing to check. It is not a sync failure and nothing in the logs will draw your attention to it.

There is an Include deleted data option that syncs deleted ads, ad groups, and campaigns into report streams. For historical reporting this is usually worth enabling, because spend that occurred against a since-deleted campaign is still spend that happened, and excluding it makes your warehouse totals fall short of your invoice.

Setting up the connection

On Airbyte Cloud, authenticate with OAuth2.0 and authorise the TikTok account. On Open Source you can use OAuth2.0 or a Sandbox Access Token. Set a start date, since data before it is not replicated, and optionally an end date, which otherwise defaults to syncing up to the current date. If your organisation restricts access by IP, add the Airbyte Cloud IP addresses to your allow list.

On the destination side, the BigQuery connector uses direct load and writes straight to final tables. Batched Standard Inserts is the default and suits ad reporting volumes. Your service account needs BigQuery User and BigQuery Data Editor, and the dataset location must match the datasets you will join against, because BigQuery cannot query across physical locations and the location is fixed at creation.

Tables are partitioned daily on the extraction timestamp rather than the report date, so filtering on the report date will not prune partitions. Since ad reporting queries almost always filter on report date, build a downstream model partitioned that way and point dashboards at it.

Frequently asked questions

Why don't my numbers match TikTok Ads Manager?

The Reporting API has roughly 11 hours of latency and metrics keep updating afterwards. Use an attribution window of at least 3 days and deduplicate on the record key so restated days replace earlier versions.

My sync fails with error 40067.

That is TikTok reporting the query is too large, which commonly affects accounts with many ads or ad groups. Reduce the Daily Reports Date Step from its default of 30 to 7 or 1 and retry.

Some of my ads are missing from the ads stream.

The stream skips records where TikTok does not return a modify time, and TikTok can omit it from Smart+ ad records. Those ads will not appear, and the sync will still report success.

Should I include deleted campaigns?

For historical spend reporting, yes. Enable Include deleted data, otherwise spend against deleted campaigns is absent and your warehouse totals will fall short of your invoice.

Get your TikTok Ads data into BigQuery

Set an attribution window of at least three days, choose your granularity before the first sync, tune the date step if you manage a large account, and model a table partitioned on report date. For other sources landing in the same warehouse, see our guides to Datadog to BigQuery and PostgreSQL to BigQuery.

Start syncing now →