> For the complete documentation index, see [llms.txt](https://docs.quanti.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.quanti.io/connectors/marketing-connectors/tiktok-organic.md). # TikTok Organic 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 {% stepper %} {% step %} **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 {% hint style="warning" %} 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. {% endhint %} {% endstep %} {% step %} **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** {% hint style="info" %} Only one TikTok Business account can be connected per connector. To sync a different account, create a new connector. {% endhint %} {% endstep %} {% step %} **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** {% endstep %} {% step %} **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 {% endstep %} {% step %} **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 {% endstep %} {% endstepper %} *** ## 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). *** ```mermaid erDiagram profile { TIMESTAMP _quanti_loaded_at PK STRING username PK STRING display_name STRING bio_description BOOLEAN is_verified BOOLEAN is_business_account } profile_snapshot_metric { TIMESTAMP _quanti_loaded_at PK STRING username PK TIMESTAMP _quanti_sync_date PK INTEGER followers_count INTEGER following_count INTEGER total_likes INTEGER videos_count STRING audience_countries STRING audience_ages STRING audience_genders } profile_daily_metric { STRING _quanti_ad_account DATE _quanti_date PK STRING _quanti_id STRING username PK DATE date PK INTEGER video_views INTEGER unique_video_views INTEGER profile_views INTEGER likes INTEGER comments INTEGER shares INTEGER daily_new_followers INTEGER daily_lost_followers INTEGER daily_total_followers INTEGER engaged_audience INTEGER bio_link_clicks STRING audience_activity } video_snapshot_metric { TIMESTAMP _quanti_loaded_at PK STRING item_id PK TIMESTAMP _quanti_sync_date PK TIMESTAMP create_time STRING caption INTEGER likes INTEGER comments INTEGER shares INTEGER video_views INTEGER reach FLOAT video_duration FLOAT total_time_watched FLOAT average_time_watched FLOAT full_video_watched_rate STRING impression_sources STRING audience_countries } profile ||--o{ profile_snapshot_metric : "username" profile ||--o{ profile_daily_metric : "username" ``` *** 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 or consult our comprehensive documentation at [https://docs.quanti.io](https://docs.quanti.io/)
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.quanti.io/connectors/marketing-connectors/tiktok-organic.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.