> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/social-media/tiktok-public.md).

# TikTok Organic

Export TikTok audience insights, video metrics, and demographic data to Google Sheets, BigQuery, or Excel automatically via Coupler.io.

TikTok Organic lets you automatically export your account's performance data—audience insights, video metrics, and demographic breakdowns—directly to Google Sheets, Excel, BigQuery, or other destinations. No manual downloads, no data silos.

## Why connect to Coupler.io?

* **Automate reporting** — Pull audience insights and video performance on a schedule without logging into TikTok
* **Combine with other data** — Join TikTok metrics with Instagram, YouTube, or other social channels using Coupler's transformations
* **Real-time dashboards** — Feed data to Looker Studio, Tableau, or AI tools like Claude and ChatGPT for instant analysis
* **Stay within data limits** — TikTok caps historical data at 60 days; Coupler helps you archive and track trends over time

## Prerequisites

* A TikTok Creator or Business account (personal accounts don't have access to analytics)
* Admin or Editor access to your TikTok account
* A destination ready (Google Sheets, Excel, BigQuery, Looker Studio, Claude, ChatGPT, or other supported platforms)

## Quick start

{% hint style="success" %}
Start with a single report type (like **Profile insights**) to test the connection. Once you see data flowing, add more report types or create a second data flow for video-level metrics.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Sign in to your TikTok Creator account.** In Coupler.io, click **Add source** and select **TikTok Organic**. You'll be prompted to authorize Coupler to access your account. Click through the OAuth flow, review the permissions, and approve.
{% endstep %}

{% step %}
**Choose your report type.** Select from:

* **Profile insights** — Overall account performance (followers, videos, views, shares)
* **Profile audience genders** — Gender breakdown of your audience
* **Profile audience countries** — Geographic distribution of viewers
* **Profile audience hourly activity** — When your audience is most active
* **Video list insights** — Individual video metrics (views, likes, comments, shares)
* **Video list top countries** — Which countries your videos are trending in
  {% endstep %}

{% step %}
**Set the date range (if applicable).** For profile and audience reports, use the date picker to set start and end dates. Remember: TikTok only provides data from the last 60 days. If you need historical trends, schedule regular exports to build your own archive.
{% endstep %}

{% step %}
**Choose your destination.** Pick where your data lands: Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude or ChatGPT. If you're appending data over time, select **Append** mode so new rows don't overwrite old ones.
{% endstep %}

{% step %}
**Run the data flow manually.** Click **Run** to pull your first batch of data. Once it completes successfully, you can schedule refreshes from the data flow details page.
{% endstep %}
{% endstepper %}

## TikTok Organic data overview

TikTok Organic gives you two layers of data: account-level insights (audience, activity patterns) and video-level performance metrics. Each report type serves a different analytics need.

## Available report types

| Report Type                      | Granularity     | Update frequency | Use case                             |
| -------------------------------- | --------------- | ---------------- | ------------------------------------ |
| Profile insights                 | Entire account  | Daily            | Track overall account growth         |
| Profile audience genders         | Gender + date   | Daily            | Understand audience composition      |
| Profile audience countries       | Country + date  | Daily            | Find geographic growth opportunities |
| Profile audience hourly activity | Hour + date     | Daily            | Discover peak engagement times       |
| Video list insights              | Per video       | Daily            | Monitor individual video performance |
| Video list top countries         | Video + country | Daily            | See regional trends by content       |

## Profile insights metrics

#### Key metrics

| Metric                  | Description                            |
| ----------------------- | -------------------------------------- |
| followerCount           | Total followers at the end of the date |
| videoCount              | Total videos you've posted             |
| viewCount               | Total video views in the period        |
| heartCount              | Total likes across all videos          |
| commentCount            | Total comments on all videos           |
| shareCount              | Total shares of your videos            |
| downloadCount           | Total downloads of your videos         |
| profiles                | Unique viewers in the period           |
| tiktok\_creation\_token | API token reference                    |

## Profile audience metrics

#### Gender breakdown

| Metric      | Description                       |
| ----------- | --------------------------------- |
| maleCount   | Male viewers                      |
| femaleCount | Female viewers                    |
| otherCount  | Non-binary or undisclosed viewers |
| date        | Report date                       |

#### Country breakdown

| Metric      | Description                         |
| ----------- | ----------------------------------- |
| country     | ISO country code (e.g., US, GB, IN) |
| countryName | Full country name                   |
| viewCount   | Views from this country             |
| date        | Report date                         |

#### Hourly activity

| Metric    | Description               |
| --------- | ------------------------- |
| hour      | Hour of day (0–23 in UTC) |
| viewCount | Views during this hour    |
| date      | Report date               |

## Video metrics

#### Video list insights

| Metric        | Description                |
| ------------- | -------------------------- |
| videoId       | Unique TikTok video ID     |
| videoTitle    | Video title or description |
| creationTime  | When the video was posted  |
| viewCount     | Total views                |
| heartCount    | Total likes                |
| commentCount  | Total comments             |
| shareCount    | Total shares               |
| downloadCount | Total downloads            |
| reachCount    | Unique viewers             |

#### Video top countries

| Metric      | Description             |
| ----------- | ----------------------- |
| videoId     | Unique video ID         |
| country     | Country code            |
| countryName | Country name            |
| viewCount   | Views from that country |

## Common metric combinations

**Audience growth tracking:** Profile insights + Profile audience countries — shows total followers and which regions are driving new viewers.

**Content optimization:** Video list insights + Video list top countries — identify your best-performing videos and which regions love them most.

**Posting strategy:** Profile audience hourly activity + Video list insights — correlate your posting time with peak engagement.

**Demographic targeting:** Profile audience genders + Profile insights — refine your content for your core demographic.

## Use cases by role

{% tabs %}
{% tab title="Content Creators" %}
Track **video-level performance** to see which formats and topics resonate. Use **hourly activity** to post when your audience is most active. Monitor **top countries** to find emerging geographic markets and tailor content accordingly.
{% endtab %}

{% tab title="Social Media Managers" %}
Compile **profile insights** into weekly/monthly reports for stakeholders. Combine **audience gender and country data** to refine targeting. Use **video performance** to pitch content ideas backed by data.
{% endtab %}

{% tab title="Marketing Teams" %}
Append **profile insights** over time to spot growth trends. Join **TikTok data with Instagram/YouTube** using Coupler's Append transformation to benchmark social performance. Feed cleaned data to Claude or ChatGPT for automated insights summaries.
{% endtab %}

{% tab title="Analytics/BI Leads" %}
Load **all report types** into BigQuery or a data warehouse. Use Append transformation to build historical time series (TikTok only provides 60 days). Create Looker Studio dashboards for real-time monitoring.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **60-day data limit** — TikTok only provides analytics for the last 60 days. Plan regular scheduled exports to build a historical archive.
* **Date macros supported** — Use macros like `{{today}}`, `{{30daysago}}` to set dynamic date ranges. See Coupler's macro documentation for details.
* **Creator vs. Business accounts** — Only Creator and Business accounts have analytics access; personal accounts cannot connect.
* **Video list data delay** — New videos may take a few hours to appear in the Video list reports.
* **No real-time data** — Reports update once daily, typically overnight.

## TikTok Organic common issues

### Connection issues

<details>

<summary>"Unauthorized" or "Permission denied" during OAuth sign-in</summary>

This usually means you're signed into a personal TikTok account. **You must use a Creator or Business account** to access analytics. Check which account you're logged into and switch if needed, then restart the OAuth flow.

</details>

<details>

<summary>"Invalid redirect URI" error after clicking authorize</summary>

Clear your browser cache and cookies, then try the OAuth flow again. If the error persists, open the TikTok authorization page in an incognito/private browser window.

</details>

<details>

<summary>Data flow gets stuck at "Connecting..."</summary>

Wait 30 seconds, then refresh the page. If it still hangs, click **Disconnect** in the source settings, then re-authenticate using the OAuth flow. TikTok sometimes times out during initial connection.

</details>

### Missing data

<details>

<summary>No data appears in the destination after running the flow</summary>

Check that your date range is within the **last 60 days**. TikTok does not provide historical data beyond 60 days. If your start date is older than 60 days ago, move it forward and run the flow again.

</details>

<details>

<summary>Profile insights show 0 for all metrics</summary>

Wait 24–48 hours after posting new videos. Profile insights update daily, and newly uploaded content may not appear immediately in the data.

</details>

<details>

<summary>Video list is empty even though I've posted videos</summary>

Newly posted videos take a few hours to appear in the Video list reports. Also, only videos posted in the selected date range will appear. Expand your date range to include recent posts.

</details>

<details>

<summary>Audience gender/country data is incomplete</summary>

TikTok only includes viewers who have a public profile with complete demographic info. Private accounts and users who haven't filled in their country/gender are excluded from these breakdowns.

</details>

<details>

<summary>Data incompleteness</summary>

> Reference from [TikTok API docs](https://business-api.tiktok.com/gateway/docs/index?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b\&language=ENGLISH\&doc_id=1776983576127490):
>
> Q1: When I set the `start_date` to a certain date (for instance a date in July) in [/business/get/](https://business-api.tiktok.com/portal/docs?id=1762228399168514), why do I only see profile data from some time later (for instance August) onwards?
>
> A: It might be due to the following reason:
>
> The data you can get from `/business/get/` depends on the availability of corresponding TikTok Analytics data in the app and at <https://www.tiktok.com/analytics>. In this case, it's likely that the TikTok account enabled TikTok Analytics only some time after the `start_date` you set. Therefore, any profile data prior to the actual date when TikTok Analytics is enabled won't be available through the API.

</details>

### Permission errors

<details>

<summary>"You don't have permission to access analytics" message</summary>

Ensure you have **Admin or Editor role** on the TikTok account. If you're a Viewer-only, ask your account admin to upgrade your access, then reconnect the data flow.

</details>

<details>

<summary>Data flow works, but only shows partial data for some videos</summary>

Private or restricted videos may not appear in reports. Check your TikTok settings and make sure videos are public.

</details>

### Data discrepancies

<details>

<summary>Follower count in the data doesn't match TikTok app</summary>

The TikTok app shows real-time follower count; the analytics API reports the count at the end of each day in UTC. Refresh the app or check the data timestamp to confirm.

</details>

<details>

<summary>Video view counts differ between TikTok and Coupler</summary>

Small differences (1–5%) can occur due to real-time vs. API reporting delays. Larger gaps usually mean the date range is off. Verify your start and end dates in the data flow settings.

</details>

<details>

<summary>Duplicate rows when using Append mode</summary>

If you're running the same report twice on the same date, you'll get duplicates. Use **Replace** mode if you want to overwrite old data, or filter duplicates in your destination after appending.

</details>

<details>

<summary><code>likes</code> and <code>audience_countries</code> data latency</summary>

Offline data (such as `likes` , and `audience_countries` ) usually have a delay of 24-48 hours (UTC Time).

> Reference from [TikTok API docs](https://business-api.tiktok.com/gateway/docs/index?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b\&language=ENGLISH\&doc_id=1746624508278786#item-link-Data%20latency%20levels):
>
> Latencies for data fields of `/business/get/` and `/business/video/list/` fall into two categories: no latency, and day-level latency.
>
> \- No latency: Real-time data (such as `username` , and `share_url` ) usually have no latency.
>
> \- Day-level data latency: Offline data (such as `likes` , and `audience_countries` ) usually have a delay of 24-48 hours (UTC Time)

</details>

<details>

<summary>Data discrepancy on <code>shares</code> field</summary>

> *Reference from* [TikTok API docs](https://business-api.tiktok.com/gateway/docs/index?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b\&language=ENGLISH\&doc_id=1776983576127490)*:*
>
> Q1: Why does the `shares` in [/business/video/list/](https://business-api.tiktok.com/portal/docs?id=1762228421622786) show more shares than the share count displayed on the TikTok web UI?
>
> A: It might be due to the following reason:
>
> The share count displayed in the `shares` field from `/business/video/list/` corresponds to the number of shares shown in the For You feed on the TikTok mobile app. It includes both external shares and internal shares sent to friends using the "Send to friends" button. In contrast, the share count displayed on the TikTok web UI only includes external shares. For example, if a video is shared externally 30 times and shared with friends within the TikTok app 20 times, the value of `shares` from the API will be 50, but the share count displayed on the TikTok web UI will be 30.

</details>

### Rate limits

<details>

<summary>"Rate limit exceeded" error</summary>

TikTok's API has strict rate limits. If you see this, wait 1 hour before running the data flow again. Avoid scheduling multiple data flows to run simultaneously on the same TikTok account.

</details>

## TikTok Organic FAQ

<details>

<summary>Do I need a business/verified account to connect?</summary>

Yes, only **Creator and Business accounts** have access to TikTok's analytics API. Personal accounts cannot connect to Coupler. If you have a Creator account, you should already have analytics available in the TikTok app; if not, go to Creator Center and enable analytics.

</details>

<details>

<summary>Why can't I see data older than 60 days?</summary>

TikTok's API only provides 60 days of historical data. However, you can use Coupler to **append new data every day**, which builds your own long-term archive. After 60 days, manually export the oldest data to a separate sheet before it rolls off.

</details>

<details>

<summary>Can I combine TikTok data with my Instagram or YouTube data?</summary>

Yes! Create separate data flows for each platform, then use Coupler's **Append** transformation to merge them into one sheet (if they have the same columns) or use **Join** to correlate them by date. This is great for social media dashboards.

</details>

<details>

<summary>How often does TikTok update its analytics?</summary>

Once per day, usually overnight UTC. Schedule your Coupler data flow to run at 1–2 AM UTC so you capture the latest data without delay.

</details>

<details>

<summary>What's the difference between Profile insights and Video list insights?</summary>

**Profile insights** show overall account metrics (total followers, views, likes, comments). **Video list insights** break down performance by individual video, so you can see which specific videos performed best.

</details>

<details>

<summary>Can I use macros for date ranges?</summary>

Yes, both the **Start date** and **End date** fields support macros like `{{today}}`, `{{30daysago}}`, and `{{firstDayOfMonth}}`. This lets your date range update automatically without manual changes. See Coupler's macro guide for the full list.

</details>

<details>

<summary>What should I do if I see a "Rate limit exceeded" error?</summary>

Wait at least 1 hour before running the data flow again. If you manage multiple TikTok accounts, stagger their scheduled runs so they don't overlap. Avoid running more than one data flow per account simultaneously.

</details>

<details>

<summary>Should I use Replace or Append mode?</summary>

Use **Append** for ongoing daily tracking—it builds your historical archive. Use **Replace** for one-off reports or if you want to overwrite old data. Remember: TikTok only provides 60 days, so appending lets you keep trends beyond that window.

</details>

<details>

<summary>Why is my newly posted video not in the Video list report?</summary>

Newly posted videos take 2–4 hours to appear in TikTok's analytics. Also check that your date range includes today's date. If the video is still not there after 24 hours, it may be in draft or restricted mode.

</details>

<details>

<summary>Can I send TikTok data to Claude, ChatGPT, or other AI tools?</summary>

Yes! Coupler supports AI destinations including Claude, ChatGPT, Cursor, Gemini, Perplexity, and OpenClaw. Create a data flow to one of these destinations and paste your TikTok metrics for instant analysis and content recommendations.

</details>

{% hint style="info" %}
For more details on available metrics and dimensions, see [Data Overview](#tiktok-organic-data-overview). For troubleshooting connection or permission issues, check [Common Issues](#tiktok-organic-common-issues).
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/social-media/tiktok-public.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
