Circle Separator6 mins read

How Do You Get TikTok Ads Data Into BigQuery?

TikTok Ads data in BigQuery is best handled through the TikTok Marketing API, a raw landing layer, and a normalized reporting table.

For a recurring pipeline, choose one of these approaches:

MethodBest forMain advantageMain limitation
TikTok Ads Manager exportOne-off analysisNo development requiredManual or email-based workflow
Managed ETL connectorTeams that want scheduled syncs with little maintenanceFast implementationConnector fees and possible schema limits
Custom TikTok API pipelineData teams and agenciesFull control over fields, logic and refreshesRequires development and ongoing maintenance

Google's published BigQuery Data Transfer Service source list includes platforms such as Google Ads and Facebook Ads, but it does not list TikTok Ads. TikTok Ads therefore usually requires a CSV workflow, a third-party connector or a custom API integration rather than a standard Google-native transfer. Google Cloud documentation

A production integration should use this flow:

TikTok Ads API
      ↓
Raw JSON or CSV landing layer
      ↓
BigQuery staging tables
      ↓
Typed and deduplicated fact tables
      ↓
Marketing dashboards, attribution and warehouse models

The reporting grain is usually:

advertiser_id + ad_id + reporting date

For campaign-level analysis, use:

advertiser_id + campaign_id + reporting date

Do not combine campaign, ad group and ad rows in one fact table without a field such as report_level. Otherwise, the same spend can be counted at multiple levels.

Option One: Export TikTok Ads Reports Manually

TikTok Ads Manager lets users create custom reports with dimensions such as campaigns, ad groups and ads. Reports can include metrics such as spend, impressions, clicks, CPM, CPC, CTR and conversions. You can download the results for loading into BigQuery. TikTok Ads help

Manual exports work when:

  • You need a historical export once.
  • A team member reviews the data manually.
  • You are testing the dimensions and metrics needed for a future pipeline.
  • The data volume is small.

TikTok also supports scheduled custom report exports delivered by email. This reduces manual work, but the process still depends on report files and email delivery. An API or warehouse connector is usually easier to monitor. TikTok Ads help

Manual Export Workflow

  1. Create a custom report in TikTok Ads Manager.
  2. Select the required dimensions and metrics.
  3. Export the report as CSV or another supported format.
  4. Upload the file to Cloud Storage.
  5. Load the file into a BigQuery staging table.
  6. Cast metrics to numeric types.
  7. Merge the rows into a reporting table.

BigQuery supports batch loading from Cloud Storage or local files in formats including CSV, newline-delimited JSON, Avro and Parquet. BigQuery documentation

Option Two: Use the TikTok Marketing API

The TikTok Marketing API is the practical choice when you need scheduled, repeatable ingestion without relying on downloaded files.

TikTok's reporting API can return advertising data at advertiser, campaign, ad group and ad levels. Depending on the selected dimensions and report type, reports can include spend, impressions, reach, clicks, conversions, video views, engagement and website event metrics. TikTok Business API documentation

What You Need Before Using the API

A custom integration requires:

  • A TikTok for Business account.
  • A registered TikTok developer account.
  • A developer application.
  • Advertiser authorization.
  • An access token.
  • The relevant advertiser ID or advertiser IDs.
  • A BigQuery project and destination dataset.

TikTok requires advertiser authorization before an application can access Marketing API functionality and ad account data. TikTok Business API documentation

Synchronous Versus Asynchronous Reports

Use a synchronous report for a small or interactive query. TikTok states that synchronous reporting can return data for up to 20,000 ads. Larger requests should be split with campaign, ad group or ad filters. TikTok Business API documentation

Use an asynchronous report for scheduled warehouse extraction and larger recurring jobs. TikTok's asynchronous reporting supports Ad Reports and uses separate task creation and download steps. TikTok Business API documentation

A typical API workflow is:

  1. Request an asynchronous report.
  2. Poll the report task status.
  3. Download the completed report.
  4. Store the original response in Cloud Storage or a raw BigQuery table.
  5. Parse dimensions and metrics.
  6. Cast numeric fields such as spend, clicks and impressions.
  7. Merge the normalized rows into a partitioned BigQuery table.
  8. Record the request ID, extraction time and source parameters.

BigQuery Table Design for TikTok Ads

A useful fact table might include:

CREATE TABLE `project.marketing.tiktok_ads_daily`
(
  advertiser_id STRING NOT NULL,
  report_level STRING NOT NULL,
  campaign_id STRING,
  campaign_name STRING,
  adgroup_id STRING,
  adgroup_name STRING,
  ad_id STRING,
  ad_name STRING,
  stat_date DATE NOT NULL,
  spend NUMERIC,
  impressions INT64,
  clicks INT64,
  reach INT64,
  conversions INT64,
  video_views INT64,
  source_updated_at TIMESTAMP,
  loaded_at TIMESTAMP NOT NULL
)
PARTITION BY stat_date
CLUSTER BY advertiser_id, campaign_id, adgroup_id, ad_id;

TikTok report responses commonly expose metric values as strings in the API documentation. Cast those values during transformation rather than leaving spend and performance metrics as text. TikTok Business API documentation

A safe natural key should include:

advertiser_id
report_level
entity_id
stat_date

The value of entity_id depends on report_level:

  • campaign_id for campaign-level rows
  • adgroup_id for ad group-level rows
  • ad_id for ad-level rows

The source query should return only one row for each natural key before the merge runs.

Example BigQuery Merge Pattern

The staging table should contain the latest extracted rows. The curated table can then be updated with a MERGE statement:

MERGE `project.marketing.tiktok_ads_daily` AS target
USING (
  SELECT
    advertiser_id,
    report_level,
    campaign_id,
    campaign_name,
    adgroup_id,
    adgroup_name,
    ad_id,
    ad_name,
    stat_date,
    SAFE_CAST(spend AS NUMERIC) AS spend,
    SAFE_CAST(impressions AS INT64) AS impressions,
    SAFE_CAST(clicks AS INT64) AS clicks,
    SAFE_CAST(reach AS INT64) AS reach,
    SAFE_CAST(conversions AS INT64) AS conversions,
    SAFE_CAST(video_views AS INT64) AS video_views,
    CURRENT_TIMESTAMP() AS loaded_at
  FROM `project.marketing.tiktok_ads_staging`
) AS source
ON target.advertiser_id = source.advertiser_id
AND target.report_level = source.report_level
AND COALESCE(target.ad_id, target.adgroup_id, target.campaign_id)
    = COALESCE(source.ad_id, source.adgroup_id, source.campaign_id)
AND target.stat_date = source.stat_date

WHEN MATCHED THEN UPDATE SET
  campaign_name = source.campaign_name,
  adgroup_name = source.adgroup_name,
  ad_name = source.ad_name,
  spend = source.spend,
  impressions = source.impressions,
  clicks = source.clicks,
  reach = source.reach,
  conversions = source.conversions,
  video_views = source.video_views,
  loaded_at = source.loaded_at

WHEN NOT MATCHED THEN INSERT (
  advertiser_id,
  report_level,
  campaign_id,
  campaign_name,
  adgroup_id,
  adgroup_name,
  ad_id,
  ad_name,
  stat_date,
  spend,
  impressions,
  clicks,
  reach,
  conversions,
  video_views,
  loaded_at
)
VALUES (
  source.advertiser_id,
  source.report_level,
  source.campaign_id,
  source.campaign_name,
  source.adgroup_id,
  source.adgroup_name,
  source.ad_id,
  source.ad_name,
  source.stat_date,
  source.spend,
  source.impressions,
  source.clicks,
  source.reach,
  source.conversions,
  source.video_views,
  source.loaded_at
);

The merge updates previously loaded rows instead of appending duplicates. Reprocess recent completed reporting periods because TikTok reporting data can arrive late or be revised.

Which TikTok Ads Fields Should You Load?

Start with a small field set that matches the reports your team will use.

Identity Fields

  • advertiser_id
  • campaign_id
  • campaign_name
  • adgroup_id
  • adgroup_name
  • ad_id
  • ad_name

Time Fields

  • Reporting day
  • Reporting hour, when hourly analysis is required
  • TikTok account timezone
  • Extraction timestamp

Delivery Metrics

  • Spend
  • Impressions
  • Reach
  • Frequency
  • Clicks
  • CTR
  • CPC
  • CPM

Conversion Metrics

  • Conversions
  • Cost per conversion
  • Conversion rate
  • Website events
  • App events
  • TikTok attribution metrics

Video and Engagement Metrics

  • Video views
  • Video views at key completion percentages
  • Likes
  • Comments
  • Shares
  • Follows
  • Profile visits

Available metrics depend on the selected report dimensions. TikTok also notes that not every dimension available in Ads Manager is available through the API. Test the report definition before finalizing the warehouse schema. TikTok Business API documentation

Important TikTok Ads Reporting Limitations

Reporting Data Is Not Always Real Time

TikTok states that asynchronous report data is refreshed periodically and that current-day data may be inaccurate. Treat completed reporting periods as the basis for dashboards and reconciliation rather than treating same-day numbers as final. TikTok Business API documentation

API and Ads Manager Totals Can Differ

TikTok documents possible differences between synchronous reports and reports downloaded from Ads Manager. When reconciling totals, compare an Ads Manager download with its asynchronous API equivalent. Do not assume that every reporting method will produce identical results. TikTok Business API documentation

Dimensions and Metrics Are Not Interchangeable

TikTok restricts which dimensions can be combined in one request. Report designs commonly use one entity ID dimension together with a time dimension. Test each combination of entity, date, targeting and conversion fields before using it in production. TikTok Business API documentation

TikTok Ads Data Does Not Equal Business Revenue

TikTok Ads data measures platform-reported delivery and attribution. It does not replace first-party order, subscription or CRM data.

For ROAS analysis, join TikTok Ads data with:

  • Orders
  • Refunds
  • Customer IDs
  • Subscription events
  • Gross and net revenue
  • Product margins
  • Lead qualification
  • Offline conversions

Use campaign, ad group and ad IDs in tracking parameters when the destination and campaign setup support them. Keep TikTok-attributed conversions separate from warehouse-attributed conversions so the two measurement systems are not presented as the same metric.

Managed Connector or Custom Pipeline?

Choose a managed connector when:

  • You need the integration quickly.
  • The team does not want to maintain OAuth and API logic.
  • Standard campaign, ad group and ad metrics are sufficient.
  • The connector supports the required TikTok accounts, dimensions and refresh schedule.

Choose a custom API pipeline when:

  • You need data from several advertiser accounts.
  • You require custom report definitions.
  • TikTok data must be joined with internal customer or revenue data.
  • You need raw payload retention and auditability.
  • Engineers can monitor API failures, permissions, quotas and schema changes.

Choose manual exports only for occasional reporting. Manual files are not a strong foundation for automated dashboards, multi-account reporting or historical backfills.

For most companies, the setup should be:

  1. Use the TikTok Marketing API for scheduled extraction.
  2. Use asynchronous reports for recurring and larger jobs.
  3. Store the unmodified API response in a raw landing table or Cloud Storage.
  4. Normalize campaign, ad group and ad identifiers into typed staging tables.
  5. Partition the curated fact table by reporting date.
  6. Cluster by advertiser, campaign and ad identifiers.
  7. Reprocess recent completed reporting periods.
  8. Validate BigQuery spend against the matching asynchronous TikTok report.
  9. Join platform data to first-party revenue in a separate attribution model.

This structure gives you automated ingestion while retaining the raw data needed for reconciliation, debugging and future reporting changes.

Next Read