Log inStart Free Trial
easyCoexistence Official APIs

TikTok video metrics through the API: views, watch time and completion

TikTok's API for Business returns each post's lifetime metrics from GET /business/video/list/, requested by name in fields: video_views, reach, likes, comments, shares and favorites, total_time_watched and average_time_watched in seconds, full_video_watched_rate, video_view_retention, impression_sources and viewer breakdowns such as audience_countries. Most counts arrive 24 to 48 hours late and stop updating 365 days after publishing.

easyCoexistence reads a TikTok video's metrics with get_social_insights from Claude, ChatGPT or your own code: name the fields you want, such as video_views, reach or full_video_watched_rate, and give the video's item_id.

video.insights

Scope needed for watch time, completion, retention, traffic sources and viewer breakdowns; the basic counts need video.list.

7 days

Inactivity after which reach, watch time, traffic sources and audience_countries can be missing for a video.

10

Most entries in a video's audience_countries and audience_cities lists.

24 to 48 h

Usual delay for video_views, likes, reach, watch time and traffic sources, in UTC.

Which metrics does a video have?

GET /business/video/list/ returns these for each post named in fields, aggregated over the post's whole life rather than the 60-day window of account metrics. Counts such as views and likes need the video.list scope on the token, while the watch, completion and retention figures need video.insights:

video_viewsViews, counted on the first playback in an impression session
reachPeople who watched the post at least once
likes, comments, sharesLifetime totals; shares include sends to friends inside TikTok
favoritesTimes the post was added to favorites
total_time_watchedSeconds viewers spent watching, in total
average_time_watchedAverage seconds viewers spent watching
full_video_watched_rateShare of viewers who finished the video
video_view_retentionShare of viewers still watching at each second
impression_sourcesWhere viewers found the post, by share
new_followersViewers who started following the account
engagement_likesShare of viewers who liked at each second
video_durationLength of the video in seconds

How do you request them?

Name them in fields, a JSON array that must include item_id whenever it lists more than one field, and pick posts with filters.video_ids. Without the filter, the endpoint pages through the account's posts, up to 20 at a time:

Metrics for one video
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
  -H 'Access-Token: <ACCESS_TOKEN>' \
  --data-urlencode 'business_id=<OPEN_ID>' \
  --data-urlencode 'fields=["item_id","video_views","reach","video_duration","total_time_watched","average_time_watched","full_video_watched_rate","impression_sources","audience_countries"]' \
  --data-urlencode 'filters={"video_ids":["<ITEM_ID>"]}'

What does the response look like?

A videos array with one object per post and the fields asked for, plus cursor and has_more for paging. TikTok's own example, trimmed, shows the units: watch times in seconds with up to three decimals, and full_video_watched_rate as a decimal, 0.0237 here:

A video's metrics, from TikTok's example
{
  "code": 0,
  "message": "OK",
  "request_id": "2021080307532501024502410704A7306F",
  "data": {
    "videos": [
      {
        "item_id": "6990565363377392901",
        "video_views": 1231,
        "reach": 154,
        "likes": 10,
        "comments": 2,
        "shares": 0,
        "video_duration": 20.0,
        "total_time_watched": 695.942,
        "average_time_watched": 4.118,
        "full_video_watched_rate": 0.0237,
        "impression_sources": [
          { "impression_source": "For You", "percentage": 0.8983 },
          { "impression_source": "Personal Profile", "percentage": 0.0904 },
          { "impression_source": "Follow", "percentage": 0.0113 }
        ],
        "audience_countries": [
          { "country": "US", "percentage": 0.7574 },
          { "country": "GB", "percentage": 0.1775 }
        ]
      }
    ],
    "cursor": 0,
    "has_more": false
  }
}

What do the traffic sources mean?

impression_sources ranks where viewers discovered the post, from the largest share to the smallest, each entry an impression_source with its percentage. TikTok documents these values:

  • For You: the For You feed.
  • Follow: the Follow feed.
  • Sound: sound pages.
  • Personal Profile: profile pages.
  • Search: search pages.
  • Direct Message: direct messages, when TikTok Studio shows that data for the account.
  • Others: everything else.

Which viewer breakdowns are there?

Four, all describing the people who watched that post rather than the account's followers, and all needing video.insights:

  • audience_genders: shares of viewers by gender, Female, Male or Other.
  • audience_countries: up to 10 countries or regions, as ISO 3166-1 alpha-2 codes.
  • audience_cities: up to 10 cities, named like US Cincinnati.
  • audience_types: NEW_VIEWER and RETURN_VIEWER, and FOLLOWER_PERCENT against NON_FOLLOWER_PERCENT.

Which metrics depend on the account type?

A few clicks and profile visits come from TikTok's Business Analytics and need more than a personal account. profile_views, the profile visits a post drove, needs an account with Advanced Access or a Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks and address_clicks need a Verified Business Account.

Why can a metric be missing or late?

Because TikTok computes most of them offline and only from TikTok Analytics. Counts and watch metrics usually lag 24 to 48 hours, while item_id, caption and links are real time. Reach, watch time, traffic sources and audience_countries can be missing for a video nobody has viewed, liked, commented on or shared for 7 days; TikTok's tip is to interact with it and retry after 24 to 48 hours. Data stops updating 365 days after publishing, and posts filtered out for violations, such as music copyright, are not returned.

How does easyCoexistence read a video's metrics?

With get_social_insights: give the video's item_id as object_id and the field names as metrics, and it returns that post's fields, looking among the account's 20 most recent posts. For an older post, your own code calls business/video/list/ with fields and filters.video_ids as parameters, using the token from get_social_credentials.

One video's metrics through MCP
get_social_insights {
  "account_id": "<ACCOUNT_ID>",
  "object_id": "<ITEM_ID>",
  "metrics": ["video_views", "reach", "average_time_watched", "full_video_watched_rate", "impression_sources"]
}

Common mistakes

  • Assuming one scale for every percentage. TikTok's examples give impression_sources as fractions that add up to 1, while its audience_cities example shows values such as 17.4921.
  • Requesting several fields without item_id. TikTok's reference warns that such a request may fail.
  • Expecting reach for an old, quiet video. TikTok can leave reach, watch time and traffic sources empty after 7 days without views, likes, comments or shares.
  • Comparing post metrics with daily account metrics. A post's figures cover its whole life, while account metrics come by day for up to 60 days.
Doing this with EasyCoexistence

For older posts, get_social_credentials gives your own code the account's token. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

Does the TikTok API give watch time per video?

Yes. total_time_watched and average_time_watched come in seconds from /business/video/list/, for tokens with the video.insights scope.

How do I get a TikTok video's completion rate through the API?

Request full_video_watched_rate in fields on /business/video/list/. TikTok defines it as the percentage of viewers who finish watching the video.

Why are reach and watch time empty for my TikTok video?

TikTok can omit them for a video with no views, likes, comments or shares in the last 7 days, and recent data lags 24 to 48 hours.

Can the API return metrics for one specific TikTok video?

Yes. Pass its ID in filters.video_ids, with item_id and the metrics you want in fields.

Keep reading

Connect your first channel in two minutes.

No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.

  • 3 days free
  • Cancel any time
  • Official APIs only
  • Monitored 24/7

Verified on