Метрики видео 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.list.
Период неактивности, после которого охват, время просмотра, источники показов и audience_countries могут отсутствовать у видео.
Большинство записей в списках audience_countries и audience_cities.
Обычная задержка для video_views, likes, reach, времени просмотра и источников показов, в UTC.
Какие метрики есть у видео?
GET /business/video/list/ возвращает их для каждой публикации, указанной в fields. Данные суммируются за всё время жизни публикации, а не за 60 дней, как метрики аккаунта. Счётчики, например просмотры и лайки, требуют на токене область video.list, а показатели времени просмотра, досмотров и удержания требуют video.insights:
Как их запросить?
Перечислите их в fields, это JSON-массив, который обязан включать item_id, если в нём больше одного поля, и выбирайте публикации через filters.video_ids. Без фильтра эндпоинт постранично перебирает публикации аккаунта, по 20 за раз:
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:
{
"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.
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 дней.
Для более старых публикаций 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
Проверено по состоянию на