Skip to main content
Connect TikTok Ads to AstroBee to analyze your campaign performance, ad spend, and engagement metrics. Get queryable access to campaigns, ad groups, creatives, and conversion data from your TikTok advertising accounts.
Experimental feature: TikTok Ads connector is currently in beta. We’re actively improving sync reliability and adding more features.

​
Prerequisites

  • A TikTok Ads Business account with active campaigns
  • Permission to access data from the TikTok Ads accounts you want to sync
  • TikTok Ads account must have campaign data
Important: TikTok prohibits access to its API from some countries in the ASIA_SOUTH cloud region. If you encounter connection issues, consider using other regions. Learn how to change the cloud provider region by following the instructions in the Error: Client IP Address Is In Banned Country List troubleshooting article.

​
Connecting TikTok Ads

You can connect TikTok Ads in two ways: from the Sources page if you’re already using AstroBee, or during the onboarding process if you’re a new user.
1

Choose Connect Sources

On the Import Data screen, click the Connect Sources card.
Onboarding screen with Connect Sources option
2

Select TikTok Ads

Click Connect next to TikTok Ads in the list of available connectors.
Available connectors including TikTok Ads
3

Start connection

A “Configure Connector” modal appears showing “TikTok Ads Not Connected”. Click the orange Connect button to begin setup.
Configure TikTok Ads modal
4

Authorize with Fivetran

AstroBee uses Fivetran to securely connect to TikTok Ads. Review the security information and click Continue.
Fivetran authorization screen
Fivetran ensures:
  • Secure: Data transfer is encrypted end-to-end and your credentials are never exposed
  • Private: Your data passes through without permanent storage
5

Authenticate with TikTok

On the Fivetran setup page, click Authorize to log in through OAuth. You’ll be redirected to TikTok to grant access.
TikTok Ads authentication configuration
Follow the Fivetran TikTok Ads setup guide for detailed instructions.
6

Configure sync settings

After authentication succeeds, configure your sync settings:
Successful authentication with sync configuration
  • Advertiser IDs: Enter specific advertiser IDs to sync selected accounts, or leave empty to sync all accounts you have access to
Click Save & Test to verify the connection.
7

Select tables to sync

Back in AstroBee, the “Configure Connector” modal shows your sync progress. Expand Sync Settings to select which tables to include.
Select TikTok Ads tables in AstroBee
Tables marked “(always synced)” are required. Common tables include:
  • advertiser: Your TikTok Ads account information and settings
  • campaign: Campaign details, budgets, and objectives
  • ad_group: Ad group settings and targeting
  • ad: Individual ad creative and performance data
  • ad_report_hourly: Hourly performance metrics for detailed analysis
Click Save Table Selection, then Continue.
8

Data layer building

A modal appears showing “Your data layer is building”. AstroBee is unifying, deduplicating, and resolving entities across your data.
Data layer building modal
This may take 10 minutes to a couple of hours. Feel free to close this and come back later.
9

Data syncing

The Sources page shows your sync progress. Your data source is syncing and the data layer will be generated automatically once syncing completes.
TikTok Ads syncing progress
It’s safe to close this window and continue working. You can connect other data sources while you wait.
10

Connection complete

Your TikTok Ads connection now appears under MY SOURCES on the Sources page. You’ll see the sync status (e.g., “Backfilling history”) while historical data loads.
TikTok Ads connection completed

​
What happens next

After connecting TikTok Ads, AstroBee automatically generates a data layer from your synced tables. Once complete, you can start querying your advertising data using natural language.
You can also edit your data layer to customize entities, add properties, or create relationships.

​
Syncing data

TikTok Ads connections use manual sync - you control when data is refreshed. To sync your latest advertising data:
  1. Navigate to the Sources page
  2. Find your TikTok Ads connection
  3. Click the sync button
AstroBee will pull the latest campaigns, ad performance, and conversion data from your TikTok Ads accounts.

​
Understanding TikTok Ads data

TikTok Ads syncs multiple related tables:
  • Campaign data: Campaign names, objectives, budgets, and status
  • Ad group data: Targeting, placement, and bidding settings
  • Ad creative: Video ads, images, text, and call-to-action settings
  • Performance metrics: Impressions, clicks, spend, conversions, and engagement
  • Hourly reports: Detailed time-series data for performance analysis
The exact tables available depend on your TikTok Ads account configuration and which features you use in TikTok Ads Manager.

​
Troubleshooting

For additional help, see Fivetran’s TikTok Ads troubleshooting guide.
Issue: Unable to authorize access to TikTok Ads.Solution:
  • Ensure you have a TikTok Ads Business account
  • Verify you have permission to access the advertiser accounts you want to sync
  • Check that you’re signed in to the correct TikTok account
  • Try re-authorizing from the beginning
  • Confirm your TikTok Ads account is not suspended
Issue: Connection fails with “Client IP Address Is In Banned Country List” error.Solution:
  • TikTok restricts API access from certain countries in the ASIA_SOUTH region
  • Follow the banned IP troubleshooting guide to change your cloud region
  • Consider using US or EU cloud regions instead
  • Contact support@astrobee.ai if you need help changing regions
Issue: Connection succeeds but no data appears in tables.Solution:
  • Verify your TikTok Ads account has active or past campaigns
  • Check that you entered the correct advertiser IDs
  • Ensure your campaigns have actually run and generated data
  • Wait for the initial sync to complete (can take 10+ minutes for accounts with extensive campaign history)
  • Trigger a manual sync to refresh data
Issue: Initial sync appears stuck or is taking longer than expected.Solution:
  • Accounts with extensive campaign history can take 30+ minutes to sync
  • Check your internet connection
  • Avoid making changes to the connection during sync
  • TikTok Ads API rate limits may slow down large syncs
  • If stuck for more than an hour, contact support at support@astrobee.ai
Issue: Some campaigns or ads don’t appear in synced data.Solution:
  • Verify you have access to those campaigns in TikTok Ads Manager
  • Check that campaigns are not archived or deleted
  • Ensure your advertiser ID configuration includes the account containing those campaigns
  • Trigger a new sync to pull the latest data
  • Review your TikTok Ads permissions for the advertiser accounts
Issue: Cannot find or sync specific advertiser accounts.Solution:
  • Find your advertiser ID in TikTok Ads Manager (usually in the URL or account settings)
  • Ensure the advertiser ID is entered correctly (numeric format)
  • Verify you have permission to access that advertiser account
  • Leave the advertiser ID field empty to sync all accessible accounts
  • Re-authenticate if you recently gained access to new accounts
Issue: Some metrics or time periods are missing from reports.Solution:
  • TikTok Ads data may have a delay of up to 48 hours for finalized metrics
  • Check your attribution window settings - they affect conversion data
  • Verify the campaigns were active during the time period you’re querying
  • Trigger a new sync to pull the latest performance data
  • Some metrics require specific TikTok Ads features to be enabled
Issue: Status shows “Backfilling history” for many hours.Solution:
  • Historical backfills for TikTok Ads can take 12+ hours for accounts with extensive campaign data
  • This is normal behavior, not a stuck sync
  • You can safely close the browser and return later
  • The sync continues in the background and your data layer will generate automatically when complete
  • If backfill exceeds 72 hours with no progress, contact support at support@astrobee.ai
Issue: Sync completed but data layer shows an error or never finishes building.Solution:
  • Check that at least one table was selected during setup
  • Verify your synced tables contain actual data (not empty)
  • Try refreshing the page to see updated status
  • If the error persists, try disconnecting and reconnecting TikTok Ads
  • Contact support at support@astrobee.ai with the error message if the issue continues

​
Next steps

Create a Data Layer

Transform your TikTok Ads data into a queryable business model

Ask Questions

Start analyzing your campaign performance and ROI with natural language