Перейти к содержимому
warmupДокументация

Тулы

Сервер предоставляет 16 тулов. Каждый соответствует эндпоинту REST API и возвращает его JSON-ответ. Ошибки API приходят как ошибка тула с HTTP-статусом и кодом, например 409 project_limit_reached.

Пометки в таблицах: чтение — тул ничего не меняет; разрушающий — большинство клиентов попросят подтверждение; внешний — тул обращается к Meta.

Проекты

Заголовок раздела «Проекты»
Тул Что делает Пометки
list_projects Все проекты со статусом, профилем, подключёнными соцсетями и лимитом тарифа. чтение
get_project Один проект по id. чтение
create_project Создать проект.
update_project Частично обновить проект. идемпотентный
delete_project Удалить проект. разрушающий

Параметры

  • get_project, delete_project: id — UUID проекта.
  • create_project: name — 1–80 символов.
  • update_project: id и любые из name, status (farm · active · paused · archived), gender (male · female), language (BCP 47, например ru-RU), geo (код страны ISO, например DE). null очищает gender, language или geo.

Подключения

Заголовок раздела «Подключения»
Тул Что делает Пометки
start_connection Начать подключение соцсети; возвращает authUrl. Тем же вызовом переподключается аккаунт, которому нужна повторная авторизация. внешний
list_pending_facebook_pages Страницы Facebook на выбор после входа. чтение
select_facebook_page Завершить подключение Facebook выбранной страницей. внешний
disconnect Отключить соцсеть от проекта. разрушающий, внешний

Параметры

  • start_connection: id, platform (facebook · instagram · threads), необязательный timezone (IANA, например Europe/Berlin) для ежедневных обновлений.
  • list_pending_facebook_pages: id, selectionId.
  • select_facebook_page: id, selectionId, pageId.
  • disconnect: id, platform.

Агент не может пройти OAuth сам: он отдаёт вам authUrl, вы открываете ссылку и подтверждаете доступ. Подробнее — Подключение соцсети.

Аналитика

Заголовок раздела «Аналитика»

Все тулы аналитики только читают и работают с отслеживаемыми аккаунтами — своими (role: own, по умолчанию) или конкурентов (role: competitor).

Тул Что возвращает
get_analytics_filters Отслеживаемые аккаунты (id, соцсеть, username) и коллекции. Вызывайте первым, чтобы получить id для фильтров.
get_analytics_overview Просмотры, посты, ER, лайки, комментарии, репосты, сохранения, подписчики с изменением к прошлому периоду и ряд по дням.
compare_platforms Посты, просмотры, лайки, комментарии, средние просмотры на пост и ER по каждой соцсети.
get_top_posts Лучшие посты периода со ссылками, подписями и метриками.
get_content_insights Эффективность по типам контента, дням недели и часам, топ хэштегов.
get_video_duration_insights Просмотры по длительности видео и лучшая длительность.
get_posting_activity Посты по дням за последние N дней и дата последнего поста.

Общие фильтры (у всех тулов аналитики, кроме get_analytics_filters — он принимает только role):

Параметр Описание
role own (по умолчанию) или competitor.
from, to Период, YYYY-MM-DD, включительно. По умолчанию — последние 30 дней. Максимум 365 дней.
tz IANA-таймзона для границ суток и часов публикаций. По умолчанию UTC.
platforms Только эти соцсети: instagram, tiktok, facebook.
groups Только аккаунты из этих коллекций.
accountIds Только эти аккаунты.

Дополнительные параметры

  • get_top_posts: sort — views (по умолчанию), er, likes, comments, shares; limit — 1–50, по умолчанию 10.
  • get_posting_activity: days — 7–365, по умолчанию 180. from и to не используются.

Как считаются цифры: Руководство по аналитике.