TikTok Ads

Last updated on Mar 05, 2024

Effective August 15, 2023, TikTok Ads will deprecate API v1.2 and support only v1.3 of the API. Hence, your Pipelines will not replicate data for the v1.2 objects.

In the API v1.3, the names and data types of some of the fields for the objects and reports have been changed. As a result, starting Release 2.15.2, Hevo will create tables for both v1.2 and v1.3 objects and reports in your Destination. The v1.3 objects will be identified by the suffix _v2. If you want tables from API v1.3 only, you can create a new Pipeline or skip the v1.2 objects from the Pipeline Overview page.

For all Pipelines created after Release 2.15.2, Hevo will ingest only the v1.3 objects and reports; they will still be suffixed with _v2.

TikTok Ads allows marketers to retrieve statistics about their ad account, ads, ad sets, and campaigns running on TikTok. Each ad account can contain one or more campaigns, which are mainly used for setting an objective and configuring a corresponding budget. Within each campaign, you can create multiple ad groups to configure settings like target audience, placements, budget, and schedule, and create ads within each group. The Ad object contains the details needed for displaying an ad, such as the format of the ad, or its creative content.

The following image illustrates the typical campaign structure in TikTok Ads:

campaign structure

Hevo uses the TikTok Marketing API to replicate your TikTok Ads data into the desired Destination database or data warehouses for scalable analysis. For this, you must authorize Hevo to access data from your TikTok Ads account.

Note: TikTok’s authentication system uses pop-ups. Therefore, you must disable ad and pop-up blockers in your internet browser to avoid issues during the Source setup.

If you reside in a country which has blocked TikTok, for example India, you need to use a VPN to connect to your TikTok Ads account and create the Pipeline. Alternatively, set up your Hevo account in any of the following instances: US, EU, or AU. Refer to Selecting your Hevo Region for the instance URLs.

Source Considerations

  • Country-specific availability: TikTok has been removed by Internet Service Providers (ISPs) in a few countries. If your Hevo account is in any of these countries, you will not be able to create Pipelines. Use a VPN to side-step this issue. Alternatively, set up your Hevo account in any of the following instances: US, EU, or AU. Refer to Selecting your Hevo Region for the instance URLs.

  • Maturity of the API : The TikTok Marketing API is still under active development and has not reached a stable state. As a result, attribution functionalities and API rate limits are prohibitive and Hevo adheres to these while running your Pipelines.

  • Attributions: For TikTok App Marketers, it is recommended to use a Mobile Measurement Partner (MMP) to track conversions from your TikTok app campaigns till other solutions, such as server-to-server and SDK, mature and can handle different attribution windows. For now, Hevo only supports a click attribution window of 7 days and a view attribution window of 1 day.


  • None.

Revision History

Refer to the following table for the list of key updates made to this page:

Date Release Description of Change
Mar-05-2024 2.21 Updated the ingestion frequency table in the Data Replication section.
Aug-07-2023 2.15 Updated section, Schema and Primary Keys to mention about the schema differences between TikTok Ads API v1.2 and v1.3.
Apr-04-2023 NA Updated section, Configuring TikTok Ads as a Source to update the information about historical sync duration.
Dec-07-2022 NA Updated section, Data Replication to reorganize the content for better understanding and coherence.
May-24-2022 1.89 New document.

Tell us what went wrong