Ctrlk
Edit

TikTok Organic

Follow our setup guide to connect TikTok Organic to QUANTI:

Prebuilt reports and definition

Prerequisites

Before connecting TikTok Organic to QUANTI, ensure you have:

  • TikTok Business account: Your TikTok profile must be a Business account. Personal and Creator accounts are not supported.

    • To convert: open the TikTok app → Settings → Manage account → Switch to Professional account → Business

  • Single account per connector: TikTok's API only allows one Business account per connector. To sync multiple accounts, create one connector per account.

Setup Instructions

1

Authorize your TikTok Business account

  • Click Continue with TikTok Business

  • You will be redirected to TikTok's authorization page

  • Log in with your TikTok Business account credentials

  • Review and approve the requested permissions

  • You will be redirected back to QUANTI automatically

Make sure you log in with a TikTok Business account. If your account is not a Business account, you will see an error. You can convert your account in the TikTok app under Settings → Manage account → Switch to Professional account → Business.

2

Confirm your account

  • QUANTI displays the details of the authenticated account: display name, username, avatar, and account type

  • Verify this is the correct account and click Continue

Only one TikTok Business account can be connected per connector. To sync a different account, create a new connector.

3

Select pre-built reports

  • Review the available pre-built reports (see section below for details)

  • All reports are selected by default — deselect any you don't need

  • At least one report must be selected to continue

  • Click Continue

4

Connector Information

  • Connector Name: A unique name for this connector (default: TikTok Organic - {display_name})

  • Dataset ID: The BigQuery dataset ID where tables will be created (default: tiktokorganic_{username})

    • Must be lowercase, start with a letter, and use only letters, numbers, and underscores

    • The dataset will be created automatically if it doesn't exist

  • Click Save to create the connector

5

Finish setup

  • For the first sync, you have the following options:

    • Activate auto-sync for recurring syncs (daily or weekly) by clicking the switch button

    • Launch a historical data recovery — maximum 60 days of history available

    • Launch a manual sync immediately by clicking the Sync now button

  • Wait for the sync to complete. Then navigate to your data warehouse to verify that tables are populated

Prebuilt reports

Profile

profile: Account profile attributes — static descriptive data about the TikTok Business account. One row per account, updated at each sync. Dimensions: username. Fields: display_name, bio_description, profile_image, profile_deep_link, is_verified, is_business_account.

profile_snapshot_metric: Cumulative account metrics captured at each sync time — a new row is inserted at every sync to historize the evolution of account KPIs. Dimensions: username, _quanti_sync_date. Metrics: followers_count, following_count, total_likes, videos_count. Also includes audience demographics as JSON arrays: audience_countries, audience_cities, audience_ages, audience_genders.

profile_daily_metric: Daily engagement metrics at account level. Each row represents one day for one account. Dimensions: username, date. Metrics: video_views, unique_video_views, profile_views, likes, comments, shares, daily_new_followers, daily_lost_followers, daily_total_followers, engaged_audience, bio_link_clicks. Business-only metrics (populated only for accounts with a configured business profile): phone_number_clicks, lead_submissions, app_download_clicks, email_clicks, address_clicks. Also includes audience_activity (hourly follower activity, stored as JSON array).

Video

video_snapshot_metric: Video-level metrics captured at each sync time — a new row is inserted per video at every sync to track the evolution of engagement over time. Dimensions: item_id, _quanti_sync_date. Fields: create_time, caption, thumbnail_url, embed_url, share_url. Lifetime cumulative metrics: likes, comments, shares, video_views, reach, video_duration, total_time_watched, average_time_watched, full_video_watched_rate. Also includes impression_sources and audience_countries (stored as JSON arrays).

Prebuilt reports and definition

Notes

  • Data refresh: Syncs run daily (default at 3:00 AM) or weekly. The default lookback window is 5 days to capture retroactive metric adjustments.

  • Historical data: Historical recovery is limited to a maximum of 60 days.

  • Metric delay: Some metrics may have a delay of 24 to 48 hours before being available via TikTok's API.

  • Token management: TikTok Business API issues long-lived tokens that do not expire automatically. Tokens can be revoked manually by the user in TikTok → Settings → Security → Third-party apps. If a token is revoked, you will need to reconnect the connector.

  • Business-only metrics: Fields such as phone_number_clicks, lead_submissions, app_download_clicks, email_clicks, and address_clicks in profile_daily_metric are only populated for accounts registered as a TikTok Business account with a configured business profile.

  • Custom reports: This connector does not support custom queries. Only the pre-built reports above are available.

Troubleshooting

Connection Issues

  • Verify that your TikTok account is a Business account (not a Creator or Personal account)

  • To convert: TikTok app → Settings → Manage account → Switch to Professional account → Business

  • If you see an "Unverified app" warning during authorization, this is expected — click Continue to proceed

  • If the connection fails, check that you have not revoked the app's permissions in TikTok Settings → Security → Third-party apps

Missing Data

  • Historical data is limited to the last 60 days — data older than that cannot be recovered

  • Some metrics may not be available immediately after publication (24–48 hour delay)

  • Business-only metrics (phone clicks, leads, etc.) will be empty if your account does not have a configured business profile

  • The video_snapshot_metric table only contains videos that were public at the time of the sync

Need Help?

Contact QUANTI support at [email protected] or consult our comprehensive documentation at https://docs.quanti.io

PreviousTikTokNextTimeOne

Last updated