How to connect TikTok Ads to Databricks, step by step

What you end up with

A Delta table in your own Databricks workspace, tiktok_ads_ad_insights, with one row per ad per day by default: impressions, clicks, spend, conversions, video views and engagement.

The connector reads the TikTok Marketing API, writes that table and repeats on a schedule. It does not model the data. What you build on top, in SQL or a notebook, is yours.

Before you start

In TikTok

A TikTok for Business user assigned to the advertiser account, and the numeric advertiser ID from TikTok Ads Manager.

In Databricks

A storage of type Databricks connected to your OWOX Data Marts project. The storage guide asks for the workspace host, the HTTP path of a SQL warehouse and a personal access token. The token’s user needs permission to create schemas and tables in the catalog you choose, and to run queries on that warehouse.

The SQL warehouse behind the HTTP path does the work, so it sets the cost. Turn on auto stop and start small. Databricks pricing shows what a short daily job is billed for.

Step 1: create the Data Mart and choose the connector

Click New Data Mart, give it a title, pick the Databricks storage and click Create Data Mart. On the Data Setup tab, set Definition Type to Connector.

Choose TikTok Ads and click Next.

Step 2: sign in, enter the advertisers and choose the data level

Continue with TikTok is the short way. Sign in as a user who can access the advertiser account and approve access. It needs no developer app.

Manually means your own TikTok developer app: an access token, an App ID and an App Secret. TikTok reviews every app, which can take up to seven business days. The credentials guide covers it.

Fill in Advertiser IDs with the numbers only. Several advertisers go in one field, separated by commas or semicolons, and they all write into the same table.

The data level

Data Level decides what one row of the performance table means. Get it right the first time.

• AUCTION_AD, the default. One row per ad per day.
• AUCTION_ADGROUP. One row per ad group per day.
• AUCTION_CAMPAIGN. One row per campaign per day.
• AUCTION_ADVERTISER. One row per advertiser per day.

The level also decides the keys the connector merges rows on, which is why you should not change it after data has been loaded. New rows would be matched on a different set of keys than the rows already in the table. If you need a second grain, create a second Data Mart with its own table.

For most reporting, keep the default. Ad level can always be summed up to campaigns. The reverse is not possible.

Step 3: choose the endpoint

Each Data Mart loads one endpoint.

• ad_insights. Daily performance at the data level you chose. The one for reporting.
• ad_insights_by_country. The same, with a country breakdown.
• campaigns, ad_groups and ads. Names, objectives, budgets, statuses and creative details.
• advertiser and audiences. Account details and custom audiences.

Step 4: choose the fields

The key fields for your data level are locked, and the panel says which ones.

Beyond impressions, clicks and spend, take the fields that are specific to TikTok: video views, two-second and six-second views, completions, and likes, comments, shares and follows.

Step 5: name the catalog, schema and table

On Databricks the destination has three levels.

The setup proposes the catalog main, a schema named after the source and a table named after the endpoint. Each is created on the first run if it does not exist. If you load several ad platforms, pointing them all at one schema keeps later queries shorter.

Click Save, then Publish & Run Data Mart. The first run loads data from the first day of the previous month and can take several minutes.

Load history and set the schedule

Backfill

Click Manual Run and choose Backfill (custom period). One backfill run covers at most 31 days. For a longer history, run consecutive periods, each after the previous one has finished.

Schedule

A Data Mart without a trigger does not run again. On the Triggers tab, add a trigger of type Connector Run: daily, weekly, monthly or at an interval.

If a report reads from this Data Mart, schedule it after the connector run, as in the example above, so it picks up the fresh data.

Each scheduled run re-requests the days set by the Reimport Lookback Window, two by default. Impressions, clicks and spend settle within a day or two. Conversions keep arriving for as long as your attribution window, so if you report on them, set the lookback at least that long.

Run History shows every run with its time and status.

One advanced setting to leave alone: Create Empty Tables. With it off, an account with no delivery yet gets no table, and later runs fail because the table is not found.

What the table looks like in Databricks

A three-level name, no quoting. With the proposed names the table is main.tiktok_ads_owox.tiktok_ads_ad_insights. Names are not case-sensitive.

The day is stat_time_day, a date column.

IDs, not names. The table carries campaign_id, adgroup_id and ad_id. Names are in the campaigns, ad_groups and ads endpoints. Load the ones you need as separate Data Marts and join on the ID.

Metrics are numbers. impressions, clicks, spend, the video counts and the engagement counts can be summed directly.

Keys and comments in the catalog. The connector declares the keys as the table’s primary key and writes each field’s description as a column comment, so the table documents itself in Catalog Explorer.

Query the data

All three queries were validated on a Databricks SQL warehouse against tables loaded by the connector. The examples use a shared schema, ads_owox, for all ad platforms.

Spend, clicks and cost per click by campaign and day, for the last 30 days:

SELECT
  stat_time_day AS date,
  campaign_id,
  SUM(impressions) AS impressions,
  SUM(clicks) AS clicks,
  SUM(spend) AS spend,
  SUM(spend) / NULLIF(SUM(clicks), 0) AS cpc
FROM main.ads_owox.tiktok_ads_ad_insights
WHERE stat_time_day >= date_sub(current_date(), 30)
GROUP BY stat_time_day, campaign_id
ORDER BY date, spend DESC;

How far people watch, by campaign:

SELECT
  campaign_id,
  SUM(impressions) AS impressions,
  SUM(video_views) AS video_views,
  SUM(video_watched_6s) AS views_6s,
  SUM(video_completion) AS completions,
  SUM(video_watched_6s)
    / NULLIF(SUM(video_views), 0) AS rate_6s,
  SUM(video_completion)
    / NULLIF(SUM(video_views), 0) AS completion_rate,
  SUM(spend) AS spend
FROM main.ads_owox.tiktok_ads_ad_insights
WHERE stat_time_day >= date_sub(current_date(), 30)
GROUP BY campaign_id
ORDER BY spend DESC;

TikTok next to LinkedIn, one row per day and channel:

SELECT
  stat_time_day AS date,
  'tiktok' AS channel,
  SUM(impressions) AS impressions,
  SUM(clicks) AS clicks,
  SUM(spend) AS spend
FROM main.ads_owox.tiktok_ads_ad_insights
GROUP BY stat_time_day

UNION ALL

SELECT
  dateRangeStart AS date,
  'linkedin' AS channel,
  SUM(impressions) AS impressions,
  SUM(clicks) AS clicks,
  SUM(costInUsd) AS spend
FROM main.ads_owox.linkedin_ads_ad_analytics
GROUP BY dateRangeStart;

Compute cpc, ctr and cpm from sums. The columns with those names hold the ratio for one ad on one day and cannot be averaged across rows.

From table to report

The third query is worth more as a published definition than as a snippet. Save it as a SQL Data Mart and everyone reads the same unified spend table.

On a Data Mart’s Destinations tab you attach reports to Google Sheets, Data Studio, Slack or email, each with its own columns and schedule. Databricks to Google Sheets walks through the scheduled report and the self-service route for business users.

Where to go next

The same five screens load the other sources into the same workspace: Facebook Ads, Google Ads and LinkedIn Ads.

On Snowflake the steps are the same and the naming rules differ: see TikTok Ads to Snowflake. For the platform itself, start with what Databricks is and how it works.

DatabricksWhat is Databricks and how does it work?October 1, 2026→DatabricksDatabricks pricing explained: DBU rates, compute types and what drives your billOctober 1, 2026→DatabricksHow to connect Facebook Ads to Databricks, step by stepOctober 1, 2026→

See all articles →