Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mage.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This source syncs ad management objects and performance insight reports from the TikTok Marketing API. It covers advertisers, campaigns, ad groups, ads, and a set of insight breakdowns (by age/gender, country, platform, and province). Authentication is via a long-lived access token issued by the TikTok Marketing API portal. The token is scoped to one or more advertiser accounts, which you list in accounts. Insight streams (ad_insights, ad_insights_by_*) sync incrementally from start_date. Entity streams (advertisers, campaigns, adgroups, ads) sync full table by default.

​
Configuration

KeyRequiredDefaultDescription
access_token✅—TikTok Marketing API access token. Obtained from the TikTok for Business API portal.
accounts✅—Comma-separated advertiser account IDs, or a YAML list. All streams sync data for these accounts.
start_date✅—Start of incremental extraction. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
end_datenowOptional upper bound for extraction.
sandbox"false"Set to "true" to use TikTok sandbox API hosts instead of production.
user_agent—User-Agent header for API calls. TikTok recommends setting this to identify your integration.
request_timeout300Request timeout in seconds.
page_size1000Number of results per API page.
include_deleted"false"Set to "true" to include deleted rows in the ads, adgroups, and campaigns streams.

​
Sample configs

Minimal — entity and insight streams for one account: 
access_token: YOUR_ACCESS_TOKEN
accounts: "1234567890123456789"
start_date: "2024-01-01T00:00:00Z"
Multiple accounts with deleted rows included: 
access_token: YOUR_ACCESS_TOKEN
accounts: "1234567890123456789,9876543210987654321"
start_date: "2024-01-01T00:00:00Z"
include_deleted: "true"
Sandbox testing: 
access_token: YOUR_SANDBOX_TOKEN
accounts: "1234567890123456789"
start_date: "2024-01-01T00:00:00Z"
sandbox: "true"

​
Streams

StreamTypeDescription
advertisersFull tableAdvertiser account details for the configured accounts.
campaignsFull tableCampaigns per advertiser. Set include_deleted: "true" to include deleted campaigns.
adgroupsFull tableAd groups per campaign.
adsFull tableIndividual ads per ad group.
ad_insightsIncrementalDaily ad-level performance metrics from start_date.
ad_insights_by_age_and_genderIncrementalAd performance broken down by age and gender.
ad_insights_by_countryIncrementalAd performance broken down by country.
ad_insights_by_platformIncrementalAd performance broken down by platform (iOS, Android, etc.).
campaign_insights_by_provinceIncrementalCampaign performance broken down by province/region.

​
How to get an access token

  1. Go to the TikTok for Business Marketing API portal.
  2. Create a new app (use the Marketing API app flow, not the consumer “TikTok for Developers” Login Kit/Share Kit flow).
  3. Under app permissions, request read access for:
    • Ad Account Management
    • Ads Management
    • Reporting
  4. Optionally add a sandbox advertiser for testing without spending budget.
  5. Authorize the app against your TikTok Ads account and generate an access token.
  6. Copy the access_token and your advertiser ID(s) into the source config.
Token expiry: TikTok Marketing API access tokens are long-lived but can expire. If syncs fail with auth errors, regenerate the token in the portal and update your config.