--- title: TikTok Ads integration | Flyweel Docs description: Connect TikTok Ads to Flyweel for unified campaign analysis. Setup guide, full metric catalog, and AI Agent Chat support on day one. url: "https://www.flyweel.co/docs/integrations/tiktok-ads" type: static generatedAt: "2026-09-18T05:57:35.722Z" --- ![Documentation hero background](https://astro-flyweel-docs.vercel.app/vision-hero.webp) # TikTok Ads integration ## How the TikTok Ads integration works[Link to this section](#how-the-tiktok-ads-integration-works) TikTok Ads connects to Flyweel through the TikTok Business API. After you choose your advertiser accounts and complete the first sync, you can review TikTok beside Google and Meta in AdGrid, ask questions through AI Agent Chat, and use supported TikTok data through Flyweel MCP. **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[Link to this section](#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[Link to this section](#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[Link to this section](#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[Link to this section](#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[Link to this section](#how-tiktok-data-syncs) Flyweel runs an initial historical backfill, then keeps your data fresh on a rolling schedule. ### Initial sync[Link to this section](#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[Link to this section](#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[Link to this section](#what-data-flyweel-imports-from-tiktok) ### Campaign data[Link to this section](#campaign-data) Campaign name, objective, status, dates, and budget. Ad group and ad metadata is imported under each campaign. ### Core performance metrics[Link to this section](#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[Link to this section](#extended-metrics) Flyweel imports 23 TikTok-specific extended metrics on top of the baseline, fully detailed in [Extended Metrics](/docs/features/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[Link to this section](#account-information) Advertiser display name, currency, timezone, and account status. ## What Flyweel cannot do with your TikTok account[Link to this section](#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[Link to this section](#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[Link to this section](#using-tiktok-data-with-the-ai-agent-and-mcp) TikTok campaigns and the full extended metric catalog are available to [AI Agent Chat](/docs/features/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](/docs/mcp/setup) to wire TikTok data into Claude, ChatGPT, Cursor, or any MCP-compatible client. ## Troubleshooting[Link to this section](#troubleshooting) ### TikTok asks me to authorise again[Link to this section](#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[Link to this section](#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[Link to this section](#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[Link to this section](#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[Link to this section](#how-to-disconnect-tiktok-ads) To remove the integration: 1. Go to **Settings → Connections**. 1. Find TikTok Ads in your connected platforms. 1. Click **Disconnect** and confirm. **Data retention**: Disconnecting stops future syncs. Historical TikTok performance data stays in Flyweel so reports and dashboards keep working. ## Next steps[Link to this section](#next-steps) - [Extended Metrics](/docs/features/extended-metrics): full per-platform metric catalog. - [AdGrid Campaign Manager](/docs/features/adgrid-campaign-manager): analyse TikTok alongside Google and Meta. - [AI Agent Chat](/docs/features/ai-agent-chat): query TikTok in natural language. - [Google Ads integration](/docs/integrations/google-ads) - [Meta Ads integration](/docs/integrations/meta-ads) ## 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 spend, impressions, clicks, CPC, CPM, CTR, reach, conversion, cost per conversion, and conversion rate baseline. See the Extended Metrics page in these docs for the full list. ### What happens to my data if I disconnect? Disconnecting stops future syncs. Your historical TikTok performance data stays in Flyweel for reporting and analysis. --- **Need help?** Email [team@flyweel.co](mailto:team@flyweel.co). ### Ready to get started? Start optimizing your ad spend today with Flyweel. [Start Free](https://signup.flyweel.co/?variant=control)