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
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.- During onboarding
- From Sources page
1
Choose Connect Sources
On the Import Data screen, click the “Connect Sources” card
2
Select TikTok Ads
Click “Connect” next to TikTok Ads in the list of available connectors
3
Start connection
Click “Connect” to begin the setup process
4
Authorize with Fivetran
AstroBee uses Fivetran to securely connect to TikTok Ads. Click “Continue” to proceed
- Secure: Data transfer is encrypted end-to-end and your credentials are never exposed
- Private: Your data passes through without permanent storage
5
Configure authentication and sync settings
Follow the setup guide on the right for detailed configuration instructions from Fivetran.
- Enter specific advertiser IDs to sync selected accounts
- Leave empty to sync all accounts you have access to
- How to find your TikTok advertiser IDs
- Understanding account permissions
- Attribution window settings
6
Test and save connection
Once configured, click “Save & Test” to verify the connection
7
Select tables to sync
Back in AstroBee, your data is being synced from TikTok Ads. This typically takes 10 seconds to 10 minutes depending on your campaign volume and data history.Once synced, select which tables to include in your analysis. Common TikTok Ads 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
8
Connection complete
Your TikTok Ads connection is now active and appears in “My Sources”
What happens next
After connecting TikTok Ads, you can create a data layer to start querying your advertising data. Click “Create Data Layer” to let AstroBee analyze your TikTok Ads tables and generate a business model for natural language queries.Syncing data
TikTok Ads connections use manual sync - you control when data is refreshed. To sync your latest advertising data:- Navigate to the Sources page
- Find your TikTok Ads connection
- Click the sync button
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
Troubleshooting
For additional help, see Fivetran’s TikTok Ads troubleshooting guide.Authentication failed
Authentication failed
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
Banned IP error
Banned IP error
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
No data syncing
No data syncing
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
Sync taking too long
Sync taking too long
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
Missing campaigns or ads
Missing campaigns or ads
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
Incorrect advertiser ID
Incorrect advertiser ID
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
Performance data incomplete
Performance data incomplete
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