Renta / Docs / Sources / TikTok Ads

TikTok Ads

TikTok Ads reports advertising statistics at the level of individual ads. You assemble the report yourself from dimensions and metrics: spend and cost metrics, impressions and clicks, conversions and results, video views by watch depth, paid engagement events, and Instant Experience statistics. Renta exports this report to your data warehouse.

A second report type, Account metadata, loads the profile of every connected ad account: name, status, balance, currency, timezone, and contact details.

Authentication

Renta uses OAuth to authenticate with TikTok Ads. You will be redirected to TikTok for Business to grant Renta limited access to your ad accounts.

Your credentials are encrypted in transit and at rest, and never stored in Renta's application database. You stay in control and can revoke access from your TikTok for Business account settings at any time.

Connect TikTok Ads source

Follow these steps to add TikTok Ads as a source in Renta using OAuth authentication.

Go to the CatalogStep 1
  1. Navigate to the Connections > Catalog section in the left sidebar.
  2. Open the Advertising category and click the TikTok Ads card.
TikTok Ads card in the Advertising category of the Renta catalog
Authorize connectionStep 2

Click Log in to your Tiktok Ads account. You will be redirected to TikTok for Business to grant access.

Authorize TikTok Ads connection page in Renta
Grant access in TikTok for BusinessStep 3

TikTok for Business shows the permissions Renta requests: Ad Account Management, Reporting, Pixel Management, and TikTok Accounts. Click Confirm. TikTok may additionally ask you to verify your identity with a code sent to the email of your TikTok account. After that you are redirected back to Renta.

TikTok for Business consent screen with the requested permissions and the Confirm button
Name the connection and saveStep 4

Finish the setup:

  1. Source name.
    Specify a name for this data source. This is used exclusively in the Renta interface.
  2. Access granted.
    Verify that the account is connected successfully.

Click Save to finish.

If your TikTok Ads authorization later changes, click Re-authorize on this source. The connection refreshes in place and every pipeline built on it keeps running.

Set up your TikTok Ads connection with source name and access granted
Source createdStep 5

The new source appears in the Sources list with the Active status. You can now use it in pipelines.

Sources list with the new TikTok Ads source

Create a pipeline

Once the source is connected, create a pipeline to sync your TikTok Ads data into your destination.

Create a TikTok Ads pipeline

Link your TikTok Ads source to a destination and configure the pipeline.

Select TikTok Ads as the sourceStep 1

In the left sidebar, click New pipeline. On the Source step, select TikTok Ads under Already connected and click Next step.

Select a source step with TikTok Ads under Already connected
Select your TikTok Ads connectionStep 2

Choose the TikTok Ads connection you created earlier and click Next step.

Select your TikTok Ads connection step
Select a destinationStep 3

On the Destination step, select your destination (for example, Google BigQuery) and click Next step.

Select a destination step with Google BigQuery
Select the destination connectionStep 4

Choose the destination connection you want to load data into and click Next step.

Select your Google BigQuery connection step

Pipeline configuration

On the final step, choose which TikTok Ads data to export and how Renta loads it.

Report configuration

Point the pipeline at the ad accounts you need.

TikTok Ads ad account and report type selection
  1. Ad accounts.
    Choose one or several TikTok Ads accounts to export data from. The list shows the ad accounts available to the authorized TikTok for Business user. Renta loads rows from every selected account into the same destination table.
  2. Report Types.
    Choose what the pipeline exports.
Report typeDescription
Statistics reportAd-level advertising statistics that you assemble from dimensions and metrics. This is the default report type.
Account metadataThe profile of each selected ad account: name, status, balance, currency, timezone, and contact details.

Parameters

Select the TikTok Ads fields to include in the destination table. The parameters you choose here define the table schema.

TikTok Ads dimensions and metrics selection with the Select All button

On the Dimensions tab, check the fields that describe the ad behind each row: Date, advertiser id and name, campaign id, name, budget and objective, ad group id, name and budget, ad id, placement type, promotion type, and optimization goal. Use the search field to find a parameter by name, or click Select All.

On the Metrics tab, check the figures to export: spend, CPC, CPM and CPA, impressions and clicks, reach and frequency, conversions and results together with their real-time variants, video views by watch depth, paid followers, likes, comments and shares, profile visits, clicks on the music disc, Duet and Stitch buttons, Instant Experience statistics, and playlist visits. The Selected tab shows everything you picked, and the Selected Parameters list below the picker lets you remove a parameter.

Whichever dimensions you pick, the statistics stay at the level of individual ads. Fields such as campaign or ad group name describe the objects the ad belongs to.

The Statistics report requires at least one metric. A configuration with dimensions only is rejected with the error "Please add at least one TikTok Ads metric".

For the Account metadata report the picker contains only dimensions: account name and status, balance and currency, timezone, country, company and contact details, and business license attributes. The destination table gets one row per selected ad account.

Include the Date dimension in the Statistics report. With it, each row in the destination table is one day, the table is partitioned by the stat_time_day column, and Renta loads data incrementally. Without it, Renta reloads the whole date range on every run.

Table name

Name the pipeline and the destination table.

TikTok Ads integration name and table name
  1. Integration name.
    The name of the pipeline. It is used exclusively in the Renta interface.
  2. Table name.
    The destination table name. You can keep the auto-generated name or enter your own.

Date range

Set the historical period to load.

TikTok Ads date range with date start and date end
  1. Date start.
    The first date of the extraction period.
  2. Date end.
    The last date of the extraction period. Leave it as Today to keep collecting new data on every run.

TikTok Ads builds each report asynchronously. Renta creates a report task, waits until TikTok finishes it, and downloads the result. Requests are split into windows of up to 30 days per ad account, so a wide historical range takes longer to load than a few days.

Overwrite period

The overwrite period defines how many recent days Renta reloads on every run.

TikTok Ads overwrite period selection

On each run, Renta re-fetches the report starting from the date of the last successful run minus the overwrite period. The affected days are deleted from the destination table and inserted again, while older data stays untouched. The options range from Without overwrite data to Overwrite all data. The default is Last 3 days.

TikTok Ads can update statistics for recent days after they are first loaded, for example when conversions are attributed to an earlier impression. Keep the overwrite period at several days to capture these updates.

Schedule

Choose how often the pipeline runs.

TikTok Ads schedule type selection
Schedule typeDescription
ManualThe pipeline runs only when triggered manually through the interface or via API.
DailyThe pipeline runs once a day at the specified update time.
IntervalThe pipeline runs at specified time intervals.
Cron ExpressionThe pipeline runs on a schedule defined by a cron expression.

For Daily schedules, set the Update time, the exact time each run starts, then click Create pipeline.

Update time selection and the Create pipeline button

Renta also supports API triggers and integration with external orchestrators such as Apache Airflow, Dagster, and Prefect. See the full scheduling documentation for details.

The new pipeline appears in the Pipelines section under the ETL tab, where you can track its runs, progress, and the destination table name.

Pipelines list with the new TikTok Ads integration

Sync strategy

The synchronization strategy depends on the report type and on whether the report includes the Date dimension.

StrategySupported report typesDescription
IncrementalStatistics report (with the Date dimension selected)Each row is one day, and the destination table is partitioned by the stat_time_day column. On every run Renta reloads the window from the last successful run minus the overwrite period to the end of the date range: those daily partitions are deleted and inserted again, and older partitions stay untouched.
Full reloadStatistics report (without the Date dimension)The table has no date column to partition by, so Renta requests the whole configured date range and replaces the dataset on every run.
Full reloadAccount metadataThe report has no date column, so Renta reloads the current state of every selected ad account on each run.

Changing the selected dimensions or metrics updates the table schema, so the next run after the change reloads the entire date range.

Frequently asked questions

Ready to get started?

Build your data pipeline today or get a personalized demo. Start free!

Need help?

Get expert support to ensure your project succeeds. We're here to help!

Feature requests?

Help shape our product! Share your ideas for new features and integrations.