How the TikTok Ads integration works
TikTok Ads connects to Flyweel through the TikTok Business API and syncs your advertiser accounts, campaigns, ad groups, ads, and daily performance reports into the Ad Grid alongside Google Ads and Meta Ads. You analyse TikTok in the same dashboards, query it through AI Agent Chat, and expose it through MCP from day one.
Read-only access: Flyweel only requests read permissions. The integration cannot create, modify, or pause campaigns, change budgets, post creatives, or access organic TikTok content.
Before you connect
You need:
- A TikTok Business account with admin access.
- At least one TikTok advertiser account with active or recent campaigns.
- Permission to authorise applications against the TikTok Business Center.
How to connect TikTok Ads to Flyweel
The connection takes under five minutes through TikTok’s standard OAuth flow.
Open the Connections page
Sign in to Flyweel and go to Settings → Connections.
Start the TikTok connection
Find the TikTok Ads card and click Connect TikTok Ads.
Authorise in TikTok Business Center
TikTok redirects you to its authorisation page. Sign in with the user that has admin access, review the requested permissions, and approve.
Select advertiser accounts
After authorisation you return to the Connections page. Use the search and Select All controls to pick the advertiser accounts to sync.
Save and sync
Click Save & Refresh to lock in your selection and trigger the initial sync.
How TikTok account structure maps to Flyweel
TikTok organises advertising under Business Center. Flyweel imports at the advertiser account level and preserves the campaign hierarchy.
| TikTok level | What Flyweel does with it |
|---|---|
| Business Center | Used for OAuth scope. Not modelled directly in Flyweel. |
| Advertiser account | The unit you select in Settings → Connections. One toggle per account. |
| Campaign | Synced with name, objective, status, schedule, and budget. |
| Ad group | Synced and rolled up under each campaign. |
| Ad | Synced with creative metadata and daily performance metrics. |
Which accounts to connect
Pick advertiser accounts based on what you want to analyse, not what you have access to.
- Active accounts first: Accounts with recent spend deliver the most insight on day one.
- Watch the volume: Large accounts with thousands of ads take longer for the initial backfill.
- Revisit periodically: Add accounts as campaigns expand, or remove accounts that have gone dormant.
- Start with priorities: Connect the highest-spend accounts first to get value immediately.
How TikTok data syncs
Flyweel runs an initial historical backfill, then keeps your data fresh on a rolling schedule.
Initial sync
After you click Save & Refresh, Flyweel pulls historical reports for each selected advertiser account. The TikTok report endpoint caps every request at 30 days, so Flyweel chunks larger date ranges automatically. Initial sync takes anywhere from a few minutes to a couple of hours depending on account volume.
Ongoing sync
- Refresh cadence: TikTok data typically runs 2 to 4 hours behind the platform.
- Auto-sync: Triggers when data is more than 15 minutes stale.
- Manual sync: Click Refresh Accounts on the Connections page to force a refresh.
- Rate limiting: Flyweel respects TikTok’s 600 requests-per-minute limit and backs off automatically when TikTok signals throttling (HTTP 200 with code 40100, parsing the retry-in window from the response).
What data Flyweel imports from TikTok
Campaign data
Campaign name, objective, status, dates, and budget. Ad group and ad metadata is imported under each campaign.
Core performance metrics
Spend, impressions, clicks, CPC, CPM, CTR, reach, conversion, cost per conversion, and conversion rate. These are the same baseline metrics Flyweel imports from every advertising platform, so cross-channel comparisons line up.
Extended metrics
Flyweel imports 23 TikTok-specific extended metrics on top of the baseline, fully detailed in Extended Metrics. The categories:
| Category | Metrics |
|---|---|
| Video | Video Plays, 2-Second Video Views, 6-Second Video Views, Video 25/50/75% Watched, Video Completed, Avg. Video Watch Time, Avg. Watch Time per User |
| Engagement | Profile Visits, Follows, Likes, Comments, Shares, Music Clicks |
| Reach | Frequency |
| Cost | Cost per 1,000 Reached |
| Conversions | Secondary Goal Results, Secondary Goal Rate |
| App | Real-Time App Installs |
| E-commerce | Total Purchase Value, Total Lead Value, Purchase ROAS |
Extended metrics are always synced and available immediately to AI Agent Chat and MCP. Use them as opt-in sortable columns in the Ad Grid.
Account information
Advertiser display name, currency, timezone, and account status.
What Flyweel cannot do with your TikTok account
For your security and to keep the integration auditable, Flyweel cannot:
- Create, edit, pause, or delete campaigns, ad groups, or ads.
- Change budgets, bids, or schedules.
- Post creatives or manage assets.
- Access organic TikTok content, your personal account, or DMs.
- Read billing or payment information.
Supported ad placements
The integration imports performance for every placement TikTok exposes through the report endpoint, including in-feed ads, TopView, Spark Ads, Search Ads, and Pangle.
Using TikTok data with the AI Agent and MCP
TikTok campaigns and the full extended metric catalog are available to AI Agent Chat and the Flyweel MCP server from the moment your first sync completes. Example queries:
- “Show me TikTok 6-second video view rate by week for the last 90 days.”
- “Compare cost per lead across TikTok and Meta for our top 10 campaigns last quarter.”
- “Which TikTok ads have the highest profile visit rate but the lowest conversion rate?”
See the MCP quickstart to wire TikTok data into Claude, ChatGPT, Cursor, or any MCP-compatible client.
Troubleshooting
TikTok asks me to authorise again
Tokens expire periodically. Flyweel detects a stale token and surfaces a reconnect prompt in-app. Open Settings → Connections, click Reconnect TikTok Ads, and complete the OAuth flow again. Selected advertiser accounts and historical data are preserved.
An advertiser account does not appear after connecting
Confirm the user that authorised TikTok has admin access to that advertiser account in Business Center, then click Refresh Accounts on the Connections page. New advertiser accounts added in TikTok after you connected may take a refresh to appear.
Sync looks delayed
TikTok data normally lags the platform by 2 to 4 hours. If the freshness timestamp on the Connections page is older than that, click Refresh Accounts to force a sync. If the issue persists, check that the TikTok account is still active and has not had its API access revoked.
Throttling
If TikTok temporarily throttles the connection, Flyweel queues the next call using the retry window TikTok returns and continues automatically. No action is needed; sync resumes as soon as the window closes.
How to disconnect TikTok Ads
To remove the integration:
- Go to Settings → Connections.
- Find TikTok Ads in your connected platforms.
- Click Disconnect and confirm.
Data retention: Disconnecting stops future syncs. Historical TikTok performance data stays in Flyweel so reports and dashboards keep working.
Frequently asked questions
Do I need a TikTok Business account to connect?
Yes. Flyweel uses the TikTok Business API, which requires a TikTok Business account with admin access to at least one advertiser account.
How far back does Flyweel pull historical data?
Flyweel pulls historical performance from your selected advertiser accounts and chunks the request to respect the TikTok API’s 30-day-per-call report limit. Larger accounts take longer to complete the initial backfill.
How often does TikTok data refresh?
TikTok data typically runs 2 to 4 hours behind the platform. Flyweel auto-syncs whenever data is more than 15 minutes stale, and you can trigger a manual sync from Settings → Connections.
Can I choose which advertiser accounts to sync?
Yes. After connecting, you select advertiser accounts individually or in bulk on the Connections page, then click Save & Refresh.
Does Flyweel see my organic TikTok posts?
No. The integration is scoped to TikTok Ads only. Flyweel cannot see organic posts, your personal TikTok account, or any non-advertising content.
Can I edit or pause campaigns from Flyweel?
No. Flyweel uses read-only access. You can analyse and report on campaigns, but campaign edits still happen inside TikTok Ads Manager.
Which TikTok-only metrics does Flyweel support?
Flyweel imports 23 TikTok-specific extended metrics across video, engagement, cost, conversions, app, and ecommerce categories, in addition to the standard baseline. See the full list in Extended Metrics.
What happens to my data if I disconnect?
Disconnecting stops future syncs. Your historical TikTok performance data stays in Flyweel for reporting and analysis.
Next steps
- Extended Metrics: full per-platform metric catalog.
- AdGrid Campaign Manager: analyse TikTok alongside Google and Meta.
- AI Agent Chat: query TikTok in natural language.
- Google Ads integration
- Meta Ads integration
Need help? Email team@flyweel.co.
