TikTok Ads

Overview

This source syncs ad management objects, audience objects, and performance insight reports from the TikTok Marketing API. It covers advertisers, campaigns, ad groups, ads, audiences, 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, audiences) sync full table by default.

Configuration

Key	Required	Default	Description
`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_date`		now	Optional 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_timeout`		`300`	Request timeout in seconds.
`page_size`		`1000`	Number of results per API page.
`include_deleted`		`"false"`	Set to `"true"` to include deleted rows in the `ads`, `adgroups`, and `campaigns` streams.
`insights_lookback_window`		`0`	Days to rewind from the saved reporting bookmark for insight streams. Never goes earlier than `start_date`.

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"
insights_lookback_window: 7

Sandbox testing:

access_token: YOUR_SANDBOX_TOKEN
accounts: "1234567890123456789"
start_date: "2024-01-01T00:00:00Z"
sandbox: "true"

Streams

Stream	Type	Description
`advertisers`	Full table	Advertiser account details for the configured `accounts`.
`campaigns`	Full table	Campaigns per advertiser. Set `include_deleted: "true"` to include deleted campaigns.
`adgroups`	Full table	Ad groups per campaign.
`ads`	Full table	Individual ads per ad group.
`audiences`	Full table	Custom audiences per advertiser, including `ad_type`. Requires TikTok Audience Management read permission.
`ad_insights`	Incremental	Daily ad-level performance metrics from `start_date`.
`ad_insights_by_age_and_gender`	Incremental	Ad performance broken down by age and gender.
`ad_insights_by_country`	Incremental	Ad performance broken down by country.
`ad_insights_by_platform`	Incremental	Ad performance broken down by platform (iOS, Android, etc.).
`campaign_insights_by_province`	Incremental	Campaign performance broken down by province/region.

How to get an access token

Go to the TikTok for Business Marketing API portal.
Create a new app (use the Marketing API app flow, not the consumer “TikTok for Developers” Login Kit/Share Kit flow).
Under app permissions, request read access for:
- Ad Account Management
- Ads Management
- Audience Management
- Reporting
Optionally add a sandbox advertiser for testing without spending budget.
Authorize the app against your TikTok Ads account and generate an access token.
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.

Adventure starts here

Deployment architecture

Getting started

Mage Agent

CI/CD

Pro only features

Infrastructure

Migration guides

Global hooks

Mage Pro API

Overview

Configuration

Sample configs

Streams

How to get an access token

​Overview

​Configuration

​Sample configs

​Streams

​How to get an access token

​Related links

Overview

Configuration

Sample configs

Streams

How to get an access token

Related links