> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the TikTok Organic data source in Adriel.

## Introduction

The TikTok Organic data source surfaces account-level and video-level organic performance for a connected TikTok Creator or Business account through the TikTok Business API (v1.3). It covers published videos, account engagement, audience demographics, and impression-source breakdowns across TikTok's discovery surfaces — For You, Following, Search, Sound, and Profile.

Personal consumer TikTok accounts are not supported, because the TikTok Business API only exposes data for Creator and Business accounts ([TikTok for Developers](https://developers.tiktok.com/doc/tiktok-api-v2-overview)). The Open ID captured at connection time is used as the business identifier on every query.

As an organic-social data source, engagement metrics, audience breakdowns, and video-level fields are standardized so widgets can aggregate alongside other sources without additional configuration.

To connect this data source, see [How to connect TikTok Organic to Adriel](/data-sources/o-z/tiktok-organic/how-to-connect).

## Data refresh strategy

### Architecture data

The account and video hierarchy is refreshed daily at 5:00 PM UTC. On first connection, videos posted within roughly the last three years (1,099 days) are retrieved, but only lifetime metrics are available for them — there are no historical daily values. Metrics accumulate in the cache from the connection date forward, and new videos appear after the next daily refresh.

A manual refresh is also available from the connection page, limited to once per day. Triggering it clears the existing cache and re-runs the full cache population.

### Reports data

Report data is refreshed on the following schedules:

* **Lifetime account data and video data** — daily at 5:00 PM UTC.
* **Daily page data** — the initial fetch covers the last 59 days; each subsequent refresh updates the most recent 3 days at 12:00 AM UTC.

<Note>
  Follower and audience metrics (follower count, demographics) have no historical backfill. Only daily snapshots are cached, starting from the day the connection is first established.
</Note>

## Architecture levels

TikTok account → Video

## Date range limits

Some time breakdowns cap how far back a single report can reach:

| Breakdown | Max range |
| --------- | --------- |
| Daily     | 93 days   |
| Weekly    | 1 year    |

When a report's date range exceeds the cap for the selected breakdown, data outside the range may be truncated.

## Metrics

<Note>
  **How to read the columns**
  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
  **API Key** in code style like `video_views` is the literal TikTok Business API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

<Note>
  **Lifetime and delta variants**
  Most performance metrics are cached once per day and are available in two forms. **Lifetime** is a snapshot of the total value at the moment the data is retrieved. **Delta** is the day-over-day change, useful for trend monitoring. For videos published before the connection date, the first delta is 0 because no prior history exists, so the sum of deltas will not equal the lifetime total. When a delta cannot be calculated on a given day (for example, API downtime), it is linearly estimated from the last available data point.
</Note>

### Views & reach

| Metric      | Description                                             | Data type | API Key       |
| ----------- | ------------------------------------------------------- | --------- | ------------- |
| Video views | Plays of the video.                                     | Number    | `video_views` |
| Impressions | Total impressions, equivalent to video views on TikTok. | Number    | `video_views` |
| Reach       | Unique users reached.                                   | Number    | `reach`       |

### Engagement

| Metric          | Description                                  | Data type  | API Key                                    |
| --------------- | -------------------------------------------- | ---------- | ------------------------------------------ |
| Likes           | Likes on the video or across the account.    | Number     | `likes`                                    |
| Comments        | Comments on the video or across the account. | Number     | `comments`                                 |
| Shares          | Shares of the video or across the account.   | Number     | `shares`                                   |
| Engagement      | Combined engagement.                         | Number     | *likes + comments + shares + video\_views* |
| Engagement rate | Engagement as a share of views.              | Percentage | *(likes + comments + shares) / views*      |

### Video performance

| Metric                  | Description                                        | Data type  | API Key                   |
| ----------------------- | -------------------------------------------------- | ---------- | ------------------------- |
| Total time watched      | Total time viewers spent watching the video.       | Duration   | `total_time_watched`      |
| Average time watched    | Average time watched per view.                     | Duration   | `average_time_watched`    |
| Full video watched rate | Share of viewers who watched the video to the end. | Percentage | `full_video_watched_rate` |
| Video duration          | Length of the video.                               | Duration   | `video_duration`          |

### Profile & followers

| Metric          | Description                                | Data type | API Key           |
| --------------- | ------------------------------------------ | --------- | ----------------- |
| Follower count  | Daily snapshot of total followers.         | Number    | `followers_count` |
| Profile views   | Views of the account profile.              | Number    | `profile_views`   |
| Page post count | Number of published videos on the account. | Number    | *derived count*   |

### Post actions & clicks

<Note>
  These video-level action metrics were added recently and return 0 when the underlying action count is not available from the TikTok Business API.
</Note>

| Metric              | Description                             | Data type | API Key               |
| ------------------- | --------------------------------------- | --------- | --------------------- |
| Favorites           | Times the video was saved to favorites. | Number    | `favorites`           |
| Post profile views  | Profile views driven by the video.      | Number    | `profile_views`       |
| Website clicks      | Clicks on the video's website link.     | Number    | `website_clicks`      |
| Phone number clicks | Taps on the phone-number button.        | Number    | `phone_number_clicks` |
| Lead submissions    | Leads submitted from the video.         | Number    | `lead_submissions`    |
| App download clicks | Taps on the app-download button.        | Number    | `app_download_clicks` |
| Email clicks        | Taps on the email button.               | Number    | `email_clicks`        |
| Address clicks      | Taps on the address button.             | Number    | `address_clicks`      |
| New followers       | New followers attributed to the video.  | Number    | `new_followers`       |

### Video metadata

| Metric            | Description                   | Data type | API Key         |
| ----------------- | ----------------------------- | --------- | --------------- |
| Post date         | Publish date of the video.    | Date      | `create_time`   |
| Post text         | Caption text of the video.    | Text      | `caption`       |
| Post link         | Shareable link to the video.  | URL       | `share_url`     |
| Post embedded URL | Embeddable URL for the video. | URL       | `embed_url`     |
| Post media        | Thumbnail image of the video. | URL       | `thumbnail_url` |

## Breakdowns

### Account & video

| Breakdown | Description                             | API Key                      |
| --------- | --------------------------------------- | ---------------------------- |
| Account   | The TikTok Creator or Business account. | `open_id`                    |
| Video     | The individual video.                   | `item_id`                    |
| Post date | Publish date of the video.              | `create_time`                |
| Post text | Caption text of the video.              | `caption`                    |
| Channel   | Surface the content was published on.   | *standardized surface label* |

### Impression source

<Note>
  Video impressions are bucketed by the discovery surface that delivered them — For You feed, Following feed, Search results, Sound page, and Profile page. Each bucket behaves as an independent breakdown value.
</Note>

| Breakdown         | Description                            | API Key              |
| ----------------- | -------------------------------------- | -------------------- |
| Impression source | Surface that delivered the impression. | `impression_sources` |

### Audience demographics

<Note>
  Demographic breakdowns return follower and audience snapshots per bucket and must be used on their own; they cannot be combined with video-level engagement breakdowns.
</Note>

| Breakdown | Description             | API Key                   |
| --------- | ----------------------- | ------------------------- |
| Country   | Country of the viewer.  | `page_audience_countries` |
| Gender    | Gender of the audience. | `audience_genders`        |

### Time & grouping

<Note>
  The TikTok Business API returns daily records; Adriel groups them into these views for reporting, so all time-grouping options are Adriel-side aggregations of the same underlying daily data.
</Note>

| Breakdown           | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily               | Split reports by day.                                        |
| Weekly (Start: Mon) | Split reports by week, starting Monday.                      |
| Monthly             | Split reports by calendar month.                             |
| Quarterly           | Split reports by calendar quarter.                           |
| Yearly              | Split reports by calendar year.                              |
| No Grouping         | Do not break down; return one aggregated row.                |
| Datasource Name     | Group by the Adriel data source name.                        |

## Limitations

* **Creator or Business accounts only** — personal consumer TikTok accounts cannot be connected, because the TikTok Business API only exposes Creator and Business account data.
* **No current-day data** — the TikTok Business API does not return data for the current calendar day; the most recent available day is yesterday (UTC) ([TikTok Business API](https://business-api.tiktok.com/portal/docs)).
* **No historical backfill for follower and audience metrics** — follower count and demographics accumulate only from the connection date forward as daily snapshots.
* **Reach is a daily unique count** — because reach reflects unique users per day, summing it across a multi-day range adds up each day's value, so a longer-period total may exceed the true number of unique users reached.
* **First-day delta is zero** — videos published before the connection date have a first delta of 0, so the sum of deltas will not equal the lifetime total.
* **Temporary content** — temporary posts such as stories are not fully implemented and may contain missing or inaccurate fields.
* **Media expiry** — associated media, such as images and videos, may expire once a video is no longer accessible through the API.
* **Older or unretrievable videos** — delta values for very old videos (3+ years) or videos that became unretrievable (deleted, restricted, or shortlisted by the platform) are not recorded.
* **Deleted data not provided** — data for an element is not available after it is deleted on the platform.
* **Token refresh disconnect** — access tokens are refreshed automatically; if the refresh exchange fails, the data source is disconnected and the account must be reauthorized. This token behavior is shared with TikTok Ads.

## API references

* [TikTok Business API portal](https://business-api.tiktok.com/portal/docs) (v1.3)

## See also

* [How to connect TikTok Organic to Adriel](/data-sources/o-z/tiktok-organic/how-to-connect) (paired how-to)
* [TikTok Ads data reference](/data-sources/o-z/tiktok/data-reference) — for paid TikTok campaigns
* [Instagram Organic data reference](/data-sources/g-n/instagram-organic/data-reference) — sister organic platform