Skip to main content
Availability
Available Airbyte CloudAvailable Airbyte OSSAvailable PyAirbyte
Support Level
Certified
Latest Version
3.9.4

TikTok Marketing

This page guides you through the process of setting up the TikTok Marketing source connector.

Prerequisites​

For Airbyte Cloud:

  • A Tiktok Ads Business account with permission to access data from accounts you want to sync

For Airbyte Open Source:

For the Production environment:

  • Access token
  • Secret
  • App ID

To access the Sandbox environment:

  • Access token
  • Advertiser ID

Setup guide​

Step 1: Set up TikTok​

  1. Create a TikTok For Business account: Link
  2. Create developer application: Link
  3. For a sandbox environment: create a Sandbox Ad Account Link

Step 2: Set up the source connector in Airbyte​

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the source setup page, select Tiktok Marketing from the Source type dropdown and enter a name for this connector.
  4. Select OAuth2.0 Authorization method, then click Authenticate your account.
  5. Log in and Authorize to the Tiktok account
  6. Choose required Start date
  7. click Set up source.

For Airbyte Open Source:

  1. Go to local Airbyte page.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the Set up the source page, enter the name for the connector and select Tiktok Marketing from the Source type dropdown.
  4. Select Production Access Token or Sandbox Access Token Authorization method, then copy and paste info from step 1.
  5. Choose required Start date
  6. Click Set up source.

Supported streams and sync modes​

StreamEnvironmentKeyIncremental
AdvertisersProd,Sandboxadvertiser_idNo
AdGroupsProd,Sandboxadgroup_idYes
AdsProd,Sandboxad_idYes
CampaignsProd,Sandboxcampaign_idYes
AdsReportsHourlyProd,Sandboxad_id, stat_time_hourYes
AdsReportsDailyProd,Sandboxad_id, stat_time_dayYes
AdsReportsLifetimeProd,Sandboxad_idNo
AdvertisersReportsHourlyProdadvertiser_id, stat_time_hourYes
AdvertisersReportsDailyProdadvertiser_id, stat_time_dayYes
AdvertisersReportsLifetimeProdadvertiser_idNo
AdGroupsReportsHourlyProd,Sandboxadgroup_id, stat_time_hourYes
AdGroupsReportsDailyProd,Sandboxadgroup_id, stat_time_dayYes
AdGroupsReportsLifetimeProd,Sandboxadgroup_idNo
AudiencesProd,Sandboxaudience_idNo
CampaignsReportsHourlyProd,Sandboxcampaign_id, stat_time_hourYes
CampaignsReportsDailyProd,Sandboxcampaign_id, stat_time_dayYes
CampaignsReportsLifetimeProd,Sandboxcampaign_idNo
CreativeAssetsImagesProd,Sandboximage_idYes
CreativeAssetsMusicProd,Sandboxmusic_idYes
CreativeAssetsPortfoliosProd,Sandboxcreative_portfolio_idNo
CreativeAssetsVideosProd,Sandboxvideo_idYes
AdvertiserIdsProdadvertiser_idYes
AdvertisersAudienceReportsDailyProdadvertiser_id, stat_time_day, gender, ageYes
AdvertisersAudienceReportsByCountryDailyProdadvertiser_id, stat_time_day, country_codeYes
AdvertisersAudienceReportsByPlatformDailyProdadvertiser_id, stat_time_day, platformYes
AdvertisersAudienceReportsLifetimeProdadvertiser_id, gender, ageNo
AdGroupAudienceReportsDailyProd,Sandboxadgroup_id, stat_time_day, gender, ageYes
AdGroupAudienceReportsByCountryDailyProd,Sandboxadgroup_id, stat_time_day, country_codeYes
AdGroupAudienceReportsByPlatformDailyProd,Sandboxadgroup_id, stat_time_day, platformYes
AdsAudienceReportsDailyProd,Sandboxad_id, stat_time_day, gender, ageYes
AdsAudienceReportsByCountryDailyProd,Sandboxad_id, stat_time_day, country_codeYes
AdsAudienceReportsByPlatformDailyProd,Sandboxad_id, stat_time_day, platformYes
AdsAudienceReportsByProvinceDailyProd,Sandboxad_id, stat_time_day, province_idYes
CampaignsAudienceReportsDailyProd,Sandboxcampaign_id, stat_time_day, gender, ageYes
CampaignsAudienceReportsByCountryDailyProd,Sandboxcampaign_id, stat_time_day, country_codeYes
CampaignsAudienceReportsByPlatformDailyProd,Sandboxcampaign_id, stat_time_day, platformYes
info

TikTok Reporting API has some Data Latency, usually of about 11 hours. It is recommended to use higher values of attribution window (used in Incremental Syncs), at least 3 days, to ensure that the connector updates metrics in already presented records.

Report Aggregation​

Reports synced by this connector can use either hourly, daily, or lifetime granularities for aggregating performance data. For example, if you select the daily-aggregation flavor of a report, the report will contain a row for each day for the duration of the report. Each row will indicate the number of impressions recorded on that day.

Performance considerations​

The connector is restricted by requests limitation. This connector should not run into TikTok Marketing API limitations under normal usage. Please create an issue if you see any rate limit issues that are not automatically retried successfully.

Reference​

Config fields reference

Field
Type
Property name
object
credentials
string
start_date
string
end_date
integer
attribution_window
boolean
include_deleted

Changelog​

VersionDatePull RequestSubject
3.9.42024-03-2036302Don't extract state from the latest record if stream doesn't have a cursor_field
3.9.32024-02-1235161Manage dependencies with Poetry.
3.9.22023-11-0232091Fix incremental syncs; update docs; fix field type of preview_url_expire_time to date-time.
3.9.12023-10-2531812Update support level in metadata, removed duplicated tracking_pixel_id field from Ads stream schema
3.9.02023-10-2331623Add AdsAudienceReportsByProvince stream and expand base report metrics
3.8.02023-10-1931610Add Creative Assets and Audiences streams
3.7.12023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
3.7.02023-10-1931493Add fields to Ads stream
3.6.02023-10-1831537Use default availability strategy
3.5.02023-10-1631445Apply minimum date restrictions
3.4.12023-08-0429083Added new is_smart_performance_campaign property to ad groups stream schema
3.4.02023-07-1327910Added include_deleted config param - include deleted ad_groups, ad, campaigns to reports
3.3.12023-07-0625423add new fields to ad reports streams
3.3.02023-07-0527988Add category_exclusion_ids field to ad_groups schema.
3.2.12023-05-2626569Fixed syncs with advertiser_id provided in input configuration
3.2.02023-05-2526565Change default value for attribution window to 3 days; add min/max validation
3.1.02023-05-1226024Updated the Ads stream schema
3.0.12023-04-0724712Added attribution window for *-reports streams
3.0.02023-03-2924630Migrate to v1.3 API
2.0.62023-03-3022134Add country_code and platform audience reports.
2.0.52023-03-2922863Specified date formatting in specification
2.0.42023-02-2322309Add Advertiser ID to filter reports and streams
2.0.32023-02-1523091Add more clear log message for 504 error
2.0.22023-02-0222309Chunk Advertiser IDs
2.0.12023-01-2722044Set AvailabilityStrategy for streams explicitly to None
2.0.02022-12-2020415Update schema types for AudienceReports and BasicReports streams.
1.0.12022-12-1620598Remove Audience Reports with Hourly granularity due to deprecated dimension.
1.0.02022-12-0519758Convert mobile_app_id from integer to string in AudienceReport streams.
0.1.172022-10-0417557Retry error 50002
0.1.162022-09-2817326Migrate to per-stream state
0.1.152022-08-3016137Fixed bug with normalization caused by unsupported nested cursor field
0.1.142022-06-2913890Removed granularity config option
0.1.132022-06-2813650Added video metrics to report streams
0.1.122022-05-2413127Fixed integration test
0.1.112022-04-2712838Added end date configuration for tiktok
0.1.102022-05-0712545Removed odd production authenication method
0.1.92022-04-3012500Improve input configuration copy
0.1.82022-04-2812435updated spec descriptions
0.1.72022-04-2712380fixed spec descriptions and documentation
0.1.62022-04-1911378updated logic for stream initializations, fixed errors in schemas, updated SAT and unit tests
0.1.52022-02-1710398Add Audience reports
0.1.42021-12-307636Add OAuth support
0.1.32021-12-108425Update title, description fields in spec
0.1.22021-12-028292Support reports
0.1.12021-11-087499Remove base-python dependencies
0.1.02021-09-185887Release TikTok Marketing CDK Connector
Was this page helpful?