Data reference - Adriel Knowledge Base

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). 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 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.

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.

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

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.

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.

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

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

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

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.

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

Audience demographics

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.

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

Time & grouping

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.

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).
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 (v1.3)

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Views & reach

​Engagement

​Video performance

​Profile & followers

​Post actions & clicks

​Video metadata

​Breakdowns

​Account & video

​Impression source

​Audience demographics

​Time & grouping

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Views & reach

Engagement

Video performance

Profile & followers

Post actions & clicks

Video metadata

Breakdowns

Account & video

Impression source

Audience demographics

Time & grouping

Limitations

API references

See also