ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Метрики видео TikTok через API: просмотры, время просмотра и досмотры

API for Business у TikTok возвращает метрики каждой публикации за всё время её жизни из GET /business/video/list/. Нужные поля перечисляются в fields: video_views, reach, likes, comments, shares и favorites, total_time_watched и average_time_watched в секундах, full_video_watched_rate, video_view_retention, impression_sources и разбивки по зрителям, например audience_countries. Большинство счётчиков приходит с задержкой 24–48 часов и перестаёт обновляться через 365 дней после публикации.

easyCoexistence читает метрики видео TikTok через get_social_insights из Claude, ChatGPT или вашего кода: укажите нужные поля, например video_views, reach или full_video_watched_rate, и item_id видео.

video.insights

Право доступа нужно для времени просмотра, досмотров, удержания, источников показов и разбивок по зрителям; базовые счётчики требуют video.list.

7 days

Период неактивности, после которого охват, время просмотра, источники показов и audience_countries могут отсутствовать у видео.

10

Большинство записей в списках audience_countries и audience_cities.

24 to 48 h

Обычная задержка для video_views, likes, reach, времени просмотра и источников показов, в UTC.

Какие метрики есть у видео?

GET /business/video/list/ возвращает их для каждой публикации, указанной в fields. Данные суммируются за всё время жизни публикации, а не за 60 дней, как метрики аккаунта. Счётчики, например просмотры и лайки, требуют на токене область video.list, а показатели времени просмотра, досмотров и удержания требуют 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

Как их запросить?

Перечислите их в fields, это JSON-массив, который обязан включать item_id, если в нём больше одного поля, и выбирайте публикации через filters.video_ids. Без фильтра эндпоинт постранично перебирает публикации аккаунта, по 20 за раз:

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>"]}'

Как выглядит ответ?

Массив videos с одним объектом на публикацию и запрошенными полями, а также cursor и has_more для постраничной навигации. Пример от TikTok, сокращённый, показывает единицы измерения: время просмотра в секундах с тремя знаками после запятой, а full_video_watched_rate в виде десятичной дроби, здесь 0.0237:

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
  }
}

Что означают источники показов?

impression_sources ранжирует, откуда зрители нашли публикацию, от самой большой доли к самой маленькой. Каждая запись является impression_source с процентом. TikTok документирует такие значения:

  • For You: лента For You.
  • Follow: лента Follow.
  • Sound: страницы звуков.
  • Personal Profile: страницы профиля.
  • Search: страницы поиска.
  • Direct Message: личные сообщения, когда TikTok Studio показывает эти данные для аккаунта.
  • Others: всё остальное.

Какие есть разбивки по зрителям?

Четыре. Все они описывают людей, которые посмотрели публикацию, а не подписчиков аккаунта, и все требуют video.insights:

  • audience_genders: доли зрителей по полу: Female, Male или Other.
  • audience_countries: до 10 стран или регионов в кодах ISO 3166-1 alpha-2.
  • audience_cities: до 10 городов в формате вида US Cincinnati.
  • audience_types: NEW_VIEWER и RETURN_VIEWER, а также FOLLOWER_PERCENT против NON_FOLLOWER_PERCENT.

Какие метрики зависят от типа аккаунта?

Часть кликов и визитов в профиль приходит из TikTok Business Analytics и требует больше, чем личный аккаунт. profile_views, визиты в профиль, которые принесла публикация, требуют аккаунта с Advanced Access или Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks и address_clicks требуют Verified Business Account.

Почему метрика может отсутствовать или запаздывать?

Потому что TikTok вычисляет большинство из них в пакетном режиме и только по TikTok Analytics. Счётчики и метрики просмотра обычно отстают на 24–48 часа, тогда как item_id, подпись и ссылки приходят в реальном времени. Охват, время просмотра, источники показов и audience_countries могут отсутствовать у видео, которое за последние 7 дней никто не смотрел, не лайкал, не комментировал и не репостил. Подсказка TikTok: взаимодействуйте с видео и повторите запрос через 24–48 часа. Данные перестают обновляться через 365 дней после публикации, а публикации, скрытые за нарушения, например авторские права на музыку, не возвращаются.

Как easyCoexistence читает метрики видео?

Через get_social_insights: передайте item_id видео как object_id, а названия полей как metrics, и инструмент вернёт поля этой публикации, выбирая среди 20 последних публикаций аккаунта. Для более старой публикации ваш код вызывает business/video/list/ с параметрами fields и filters.video_ids, используя токен из 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"]
}

Распространённые ошибки

  • Предположение об одной шкале для всех процентов. В примерах TikTok impression_sources даны долями, в сумме дающими 1, а пример audience_cities показывает значения вида 17.4921.
  • Запрос нескольких полей без item_id. В справке TikTok сказано, что такой запрос может завершиться ошибкой.
  • Ожидание охвата у старого, тихого видео. TikTok может оставлять охват, время просмотра и источники показов пустыми, если за 7 дней не было просмотров, лайков, комментариев или репостов.
  • Сравнение метрик публикации с ежедневными метриками аккаунта. Показатели публикации охватывают всё её время, а метрики аккаунта выдаются по дням за период до 60 дней.
Настройка с EasyCoexistence

Для более старых публикаций get_social_credentials даёт вашему коду токен аккаунта. От US$ 9 до US$ 0,75 за подключение в месяц, по мере добавления подключений, с бесплатным пробным периодом в 3 дня.

Часто задаваемые вопросы

У TikTok API есть время просмотра по видео?

Да. total_time_watched и average_time_watched приходят в секундах из /business/video/list/ для токенов с областью video.insights.

Как получить долю досмотров видео TikTok через API?

Запросите full_video_watched_rate в fields на /business/video/list/. TikTok определяет её как процент зрителей, досмотревших видео до конца.

Почему охват и время просмотра пустые у моего видео в TikTok?

TikTok может не отдавать их для видео без просмотров, лайков, комментариев или репостов за последние 7 дней, а свежие данные отстают на 24–48 часа.

Может ли API вернуть метрики одного конкретного видео TikTok?

Да. Передайте его ID в filters.video_ids, а item_id и нужные метрики в fields.

Читайте дальше

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

Проверено по состоянию на