Advanced Analytica Advanced Analytica: IBOM
← All connectors
TikTok Marketing logo

Source connector

TikTok Marketing

Set up TikTok Marketing as a source and move its data into your chosen destination.

Version 5.4.0 certified generally available

TikTok Marketing

Use this page to set up the TikTok Marketing source connector and find reference information.

Prerequisites

For Airbyte Cloud:

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

For Airbyte Open Source:

For the Production environment (OAuth2.0), you need:

  • Access token
  • Secret
  • App ID

For the Sandbox environment, you need:

  • Access token
  • Advertiser ID

Set up the connector

Step 1: Set up TikTok Marketing

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

Step 2: Set up the source in Airbyte

Airbyte Cloud

  1. Log into your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select TikTok Marketing from the Source type dropdown.
  4. Enter a name for the TikTok Marketing connector.
  5. Select OAuth2.0 as the authorization method, then click Authenticate your account.
  6. Log in and authorise the TikTok account.
  7. Choose a Start date. The connector doesn’t replicate data from before this date.
  8. Optionally, set an End date to limit how far forward the connector replicates data. Without this setting, it syncs data through the current date.
  9. Optionally, adjust the Attribution window (default: 3 days, range: 0–364 days). This setting controls how far back the connector updates metrics for incremental report streams. A higher value helps capture delayed attribution data.
  10. Optionally, adjust the Daily Reports Date Step (default: 30 days, range: 1–30). This setting controls how many days each daily report API request covers. Use the default of 30 for most accounts. If TikTok rejects an oversized request (error 40067), the connector splits the date range in half and retries. It continues splitting down to one day, so you don’t need to lower this value for that error. Smaller values make more API requests from the start. However, splitting restarts for every date range. Accounts that often encounter error 40067 sync faster with a smaller value, such as 7.
  11. Optionally, enable Include deleted data to sync deleted ads, ad groups, and campaigns in report streams.
  12. Click Set up source.

Airbyte Open Source

  1. Go to the Airbyte Open Source dashboard.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the Set up the source page, name the connector and select Tiktok Marketing from the Source type dropdown.
  4. Select OAuth2.0 or Sandbox Access Token as the authorization method. Then enter the credentials from step 1. With OAuth2.0, the Advertiser ID is optional. Leave it empty to sync every advertiser available through the access token. Set it to sync one advertiser. With Sandbox Access Token, the Advertiser ID is required.
  5. Choose a Start date. The connector doesn’t replicate data from before this date.
  6. Optionally, set an End date to limit how far forward the connector replicates data. Without this setting, it syncs data through the current date.
  7. Optionally, adjust the Attribution window (default: 3 days, range: 0–364 days). This setting controls how far back the connector updates metrics for incremental report streams. A higher value helps capture delayed attribution data.
  8. Optionally, adjust the Daily Reports Date Step (default: 30 days, range: 1–30). This setting controls how many days each daily report API request covers. Use the default of 30 for most accounts. If TikTok rejects an oversized request (error 40067), the connector splits the date range in half and retries. It continues splitting down to one day, so you don’t need to lower this value for that error. Smaller values make more API requests from the start. However, splitting restarts for every date range. Accounts that often encounter error 40067 sync faster with a smaller value, such as 7.
  9. Optionally, enable Include deleted data to sync deleted ads, ad groups, and campaigns in report streams.
  10. Click Set up source.

Supported sync modes

The TikTok Marketing source connector supports these sync modes:

  • Full Refresh
  • Incremental

Supported streams

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_idNo
CreativeAssetsPortfoliosProd,Sandboxcreative_portfolio_idNo
CreativeAssetsVideosProd,Sandboxvideo_idYes
AdvertiserIdsProdadvertiser_idNo
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
SparkAdsProdspark_ads_post_idNo
PixelsProdpixel_idNo
PixelInstantPageEventsProd-No
PixelEventsStatisticsProd-No
AdsReportsByCountryDailyProdad_id, stat_time_day, country_codeYes
AdsReportsByCountryHourlyProdad_id, stat_time_hour, country_codeYes
AdGroupsReportsByCountryDailyProdadgroup_id, stat_time_day, country_codeYes
AdGroupsReportsByCountryHourlyProdadgroup_id, stat_time_hour, country_codeYes

Streams marked Prod are only available when you authenticate with OAuth2.0. They don’t appear in the connector’s catalog when you authenticate with a Sandbox Access Token.

The Campaigns stream retrieves campaigns for every buying type: Auction, TopView (Reservation), and Reach & Frequency (Reservation). The connector makes a separate API call for each buying type. The TikTok API can’t combine TopView with other buying types in one request.

Smart+ ad coverage

The ads stream uses modify_time as its incremental cursor. It skips records when TikTok doesn’t return this field. TikTok can omit modify_time from Smart+ ad records, so these records don’t appear in the stream.

:::info

The TikTok Reporting API has data latency of approximately 11 hours. Set an attribution window of at least 3 days for incremental syncs. This ensures the connector captures updated metrics in existing records.

:::

Report aggregation

You can aggregate performance data in synced reports using hourly, daily, or lifetime granularity. For example, select daily aggregation to include one row for each day in the report period. Each row shows the impressions recorded that day.

Performance considerations

The TikTok Marketing API rate limits restricts the connector. Under normal use, the connector shouldn’t encounter TikTok Marketing API limits. TikTok applies rate limits per access token and per advertiser. The connector backs off and retries when TikTok throttles a request. This applies to errors 40016, 40100 and 40133, “requests made too frequently”. If throttling continues to fail a sync, check that only one Airbyte connection uses those TikTok credentials at a time. If automatic retries don’t resolve a rate limit issue, create an issue.

TikTok returns most errors with HTTP 200 status and an error code in the response body. The connector automatically retries these transient TikTok API errors. It retries each failed request up to 9 times, waiting 60 seconds before each retry:

  • 60001: service maintenance. If all retries fail, wait for the maintenance period to end and run the sync again.
  • 50000, 51002, 51004, 51041: transient server-side errors.

If a resource is inaccessible or no longer exists (error 40002), the connector skips it and continues syncing.

If TikTok returns a permission error (error 40001), the connector fails the sync with a configuration error instead of retrying. The access token can’t call an endpoint required by a selected stream. Check that the developer application’s permissions include the data you’re syncing. Then re-authorise the connector and run the sync again. The PixelEventsStatistics stream is an exception. If an advertiser can’t read a pixel, the connector skips that advertiser and continues.

For daily report streams, TikTok may return error 40067 (“query too large”) for an advertiser. The connector then splits that advertiser’s date range in half and retries each half. It repeats this process down to a single day when needed. Other advertisers aren’t affected, and you don’t need to change the Daily Reports Date Step setting. This error typically affects accounts with many ads or ad groups. However, splitting restarts for every date range. If your account often encounters this error, a smaller step, such as 7, makes syncs faster. If TikTok rejects a single day as too large, the sync fails with a transient error. The connector retries it automatically. If failures continue, find the affected advertiser and date in the sync logs. Then deselect the affected stream or choose a coarser report. For example, use ad groups or campaigns instead of ads. Disabling Include deleted data can also reduce the request size.

Upgrade the connector

For breaking changes and migration steps, see the TikTok Marketing Migration Guide.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
5.4.02026-11-0490968Add website Place an Order metrics (on_web_order, total_on_web_order_value, cost_per_on_web_order, value_per_on_web_order, on_web_order_rate) to the ad, ad group and campaign daily report streams
5.3.42026-10-2189016Include the TikTok Marketing API error code in the message of sync failures caused by unhandled TikTok API errors
5.3.32026-10-2089410Update dependencies
5.3.22026-10-1689015Retry TikTok internal service timeout errors (codes 51001 and 51043) instead of failing the sync
5.3.12026-10-1388840Update dependencies
5.3.02026-10-0587641Split a daily report date range in half and retry when TikTok rejects it as too large (error 40067), instead of failing and asking to lower the Daily Reports Date Step; back off on throttling errors 40016 and 40133
5.2.02026-09-1485820Add Website, App and Shop conversion metrics to the daily report streams
5.1.192026-09-2987372Update dependencies
5.1.182026-09-2286854Update dependencies
5.1.172026-09-2179183Classify TikTok API error code 40001 (PERMISSION_ERROR) as config_error instead of system_error
5.1.162026-09-1586277Update dependencies
5.1.152026-09-1185796Stop enabling production-only streams for legacy configs with an empty secret
5.1.142026-09-0985187Retry transient TikTok API error 51002
5.1.132026-09-0885704Update dependencies
5.1.122026-08-1884765Update dependencies
5.1.112026-08-1284290Widen retry budget and retry transient TikTok API errors 51041 and 51004
5.1.102026-08-1184199Retry transient TikTok API error 50000
5.1.92026-08-1184132Update dependencies
5.1.82026-07-2883194Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override
5.1.72026-07-281082Roll Cloud back to 5.1.5 — 5.1.6 is built on SDM 7.23.7, which breaks bundled custom components
5.1.62026-07-2883151Update dependencies
5.1.52026-07-2182620Update dependencies
5.1.42026-07-1481448Add smart_plus_ad_id field to ads stream
5.1.32026-07-1482045Update dependencies
5.1.22026-06-3081267Update dependencies
5.1.12026-06-2380705Update dependencies
5.1.02026-06-1880061Add configurable report_granularity setting (default 30 days) to control daily report date step size; surfaces error 40067 as a config error with actionable guidance on daily report streams
5.0.112026-06-1680094Update dependencies
5.0.102026-06-0979549Update dependencies
5.0.92026-06-0278999Update dependencies
5.0.82026-04-2976062Add support for TopView and Reach & Frequency campaigns by including all buying types in campaigns stream
5.0.72026-04-2877465Update dependencies
5.0.62026-04-2176807Update dependencies
5.0.52026-03-3175063Update dependencies
5.0.42026-03-2474376Handle TikTok API error 60001 (service maintenance) as retryable instead of fatal; ignore error 40002 (resource not accessible or does not exist)
5.0.32026-03-1274762Promoting release candidate 5.0.3-rc.1 to a main version.
5.0.3-rc.12026-03-0574085Add missing video engagement metrics to audience report streams
5.0.22026-03-0373111Update dependencies
5.0.12026-02-2473633Fix UTC timezone mismatch causing data loss for ahead-of-UTC accounts
5.0.02026-02-1773357Fix currency field type from boolean to string in pixels events schema
4.8.142026-02-1673314Fix pixel_instant_page_events stream failing on unsupported objective/optimization combinations (error 40002) by ignoring invalid parameter combos
4.8.132026-01-2064958Update dependencies
4.8.122026-01-1570241Fix pixel_events_statistics stream: pixel_ids format, date_range calculation, and add error handler to skip advertisers without pixel permissions
4.8.112026-01-1571773Finalize progressive rollout for version 4.8.11
4.8.11-rc.12025-11-1465623Fix missing deleted data on some streams
4.8.102025-11-0469170Revert api budget and concurrency back to a safe number
4.8.92025-10-3069101Revert aggressive rate limiting
4.8.82025-10-2969082Aggressively fail on rate limiting issues
4.8.72025-10-2969081Reduce concurrency
4.8.62025-10-2969075Add API Budget
4.8.52025-10-2969074Improving on rate limiting issue.
4.8.42025-10-0867432Promoting release candidate 4.8.4 to a main version.
4.8.4-rc.12025-09-3066823Up CDK version to 7.
4.8.32025-09-2366584Promoting release candidate 4.8.3-rc.1 to a main version.
4.8.3-rc.12025-09-1662058Add new video metrics in ads_reports streams
4.8.22025-09-1666233Promoting release candidate 4.8.2-rc.1 to a main version.
4.8.2-rc.12025-09-1165527Fix missing records for hourly streams: remove record filter
4.8.12025-09-1166161Promoting release candidate 4.8.1-rc.1 to a main version.
4.8.1-rc.12025-09-0565602Add record filter to ads stream to filter records without modify_time.
4.8.02025-06-2462048Promoting release candidate 4.8.0-rc.1 to a main version.
4.8.0-rc.12025-06-1661580Convert to manifest-only format
4.7.02025-03-1055681Ads / AdGroups report by country streams
4.6.22024-10-3048003Add new metrics to ads_reports_daily stream
4.6.12025-03-2251959Update dependencies
4.6.02025-03-0955669Add Pixels, PixelInstantPageEvents, PixelEventsStatistics streams
4.5.02025-03-0745081Add SparkAds stream
4.4.02025-03-0755242Promoting release candidate 4.4.0-rc3 to a main version.
4.4.0-rc32025-03-0455194Resolve state format issue
4.4.0-rc22025-02-2053645Remove stream_state interpolation and custom cursors
4.4.0-rc12025-01-2951584Update to concurrent CDK
4.3.72025-01-1147118Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
4.3.62024-10-1246855Update dependencies
4.3.52024-10-0946676Fix error handling for codes 40100 and 50002
4.3.42024-10-0546164Update dependencies
4.3.32024-09-2145790Update dependencies
4.3.22024-09-1445488Update dependencies
4.3.12024-09-0745270Update dependencies
4.3.02024-09-0344910Migrate to CDK v4
4.2.52024-08-3144954Update dependencies
4.2.42024-08-2443783Update dependencies
4.2.32024-08-1944048Fix include_deleted toggle
4.2.22024-08-0342822Update dependencies
4.2.12024-07-2042375Update dependencies
4.2.02024-07-1742005Migrate to CDK v3.5.3
4.1.02024-07-1742004Migrate to CDK v2.4.0
4.0.42024-07-1341695Update dependencies
4.0.32024-07-1041370Update dependencies
4.0.22024-07-0941153Update dependencies
4.0.12024-07-0640915Update dependencies
4.0.02024-07-0138316Migration to low-code CDK; Support include deleted statuses for Ads, Ad Groups and Campaign streams.
3.9.102024-06-2540373Update dependencies
3.9.92024-06-2240133Update dependencies
3.9.82024-06-0639253[autopull] Upgrade base image to v1.2.2
3.9.72024-05-1538250Replace AirbyteLogger with logging.Logger and upgrade to latest base image
3.9.62024-04-1936665Updating to 0.80.0 CDK
3.9.52024-04-1236665Schema descriptions
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
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.