Instagram Graph API: як отримати доступ і токен для статистики

Будь-яка зовнішня аналітика Instagram — свій дашборд, скрипт, готовий self-hosted продукт — починається з одного й того самого: access token до Instagram Graph API. Процес його отримання нескладний, але інтерфейс Meta for Developers заплутаний, термінологія змінюється щороку, а половина інструкцій в інтернеті описує старий застарілий Basic Display API. Нижче — актуальний покроковий шлях до робочого токена зі статистикою, плюс розбір типових помилок.

Що дає Graph API і чого не дає

Instagram Graph API — єдиний легальний спосіб отримати внутрішню статистику акаунта програмно: охоплення, покази, збереження, поширення, приріст підписників, демографію аудиторії. Це ті самі дані, що у вбудованій статистиці застосунку, але через API їх можна забирати щодня, накопичувати і будувати власні звіти.

Важливі межі: API віддає статистику лише вашого акаунта (або акаунтів, до яких вам надали доступ) — «подивитись метрики конкурента» через нього не можна. І працює він тільки з професійними акаунтами.

Крок 1: переведіть акаунт у Business або Creator

Особисті акаунти статистику через API не віддають — це обмеження Meta. Перемкнутися: Instagram → Налаштування → Тип акаунта та інструменти → Перейти на професійний акаунт. Це безкоштовно і займає дві хвилини. Для бізнесу обирайте Business, для авторів — Creator: для статистики через API підходять обидва.

Рекомендація з практики: прив'яжіть Instagram до Facebook-сторінки. Для частини сценаріїв доступу це обов'язково, і навіть там, де ні, — зв'язка робить поведінку API передбачуванішою.

Крок 2: створіть застосунок у Meta for Developers

1. Зайдіть на developers.facebook.com під своїм акаунтом Facebook.
2. My Apps → Create App.
3. На кроці вибору use case оберіть «Manage messaging & content on Instagram» — саме цей варіант відкриває доступ до Instagram API для роботи з контентом і статистикою. Не обирайте «Other»/«None»: потім доведеться діставати потрібні продукти вручну.
4. Заповніть назву застосунку і контактний email, створіть застосунок.

«Застосунок» тут — просто контейнер для прав доступу і токенів. Публікувати його в App Review для особистого використання не потрібно: у режимі розробки він повноцінно працює з акаунтами, що мають до нього роль.

Крок 3: додайте permission instagram_business_manage_insights

Дозволи (permissions) визначають, що саме зможе токен. Для статистики ключовий — instagram_business_manage_insights: він відкриває ендпоінти insights по акаунту і по окремих публікаціях (охоплення, saves, shares, демографія, приріст підписників).

У налаштуваннях застосунку відкрийте розділ Instagram → API setup, підключіть свій Instagram-акаунт до застосунку і переконайтеся, що в списку дозволів при генерації токена відмічений instagram_business_manage_insights. Якщо плануєте надалі ще й публікувати через API — додайте відповідні content-дозволи, але для аналітики достатньо insights.

Крок 4: згенеруйте access token

У тому ж розділі Instagram → API setup є кнопка генерації токена для підключеного акаунта. Натискаєте, підтверджуєте дозволи у вікні Instagram — отримуєте довгий рядок виду IGAA.... Це і є access token.

Що треба знати про життя токенів:

Тип токена	Термін життя	Особливість
Короткоживучий	~1 година	Видається за замовчуванням у частині флоу
Довгоживучий	~60 днів	Отримується обміном короткоживучого або одразу в API setup
Оновлений довгоживучий	+60 днів	Оновлюється запитом до refresh_access_token

Практичний висновок: одразу беріть довгоживучий токен і поставте нагадування (або автоматику) на оновлення раз на 1,5–2 місяці. «Дашборд раптом перестав оновлюватись» у 9 з 10 випадків означає протухлий токен.

Крок 5: перевірте токен одним запитом

Перш ніж вставляти токен кудись, перевірте його в терміналі:

curl "https://graph.instagram.com/me?fields=id,username&access_token=ВАШ_ТОКЕН"

Якщо у відповідь прийшов ваш username — токен живий. Далі перевірте insights:

curl "https://graph.instagram.com/me/insights?metric=reach&period=day&access_token=ВАШ_ТОКЕН"

Цифри у відповіді означають, що permission на статистику працює і можна підключати аналітику.

Типові помилки і як їх лікувати

Симптом	Причина	Рішення
(#10) Permission denied на insights	Немає instagram_business_manage_insights	Перегенеруйте токен із цим дозволом
Invalid OAuth access token	Токен протух або скопійований з пробілом	Згенеруйте новий, копіюйте повністю
Порожня демографія	Менше ~100 підписників	Обмеження Meta, чекати росту акаунта
API не бачить акаунт	Акаунт особистий, не Business/Creator	Перемкнути тип акаунта (крок 1)
Метрика повертає помилку	Метрика недоступна для цього типу медіа чи періоду	Звірити список метрик для media type у документації
Все працювало і зламалось через 2 міс	Закінчився довгоживучий токен	Оновлення через refresh_access_token, поставити автоматику

Куди вставити токен: готовий дашборд замість самописних скриптів

Токен сам по собі — лише перепустка. Щоб отримати з нього користь, потрібна система, яка щодня забирає метрики, накопичує історію і малює звіти. Якщо не хочете писати її самостійно, є безкоштовний open-source Instagram Dashboard від MaxICo Labs: self-hosted, розгортається через Docker за 10 хвилин, а токен вставляється прямо в інтерфейсі — заходите в ⚙ Settings, вставляєте рядок IGAA..., і дашборд починає збирати KPI, ER% по публікаціях, ріст підписників із маркерами Reels і демографію. Жодного редагування конфігів на сервері; всі API-роути закриті авторизацією, токен зберігається лише у вашому сховищі. Подивитись живе демо: inst-dashbord.maxicolabs.com.

Що робити агенції з кількома клієнтами

Якщо ви ведете кілька акаунтів, не намагайтеся обслужити всіх одним токеном — у кожного клієнтського акаунта свій токен зі своїми правами. Робочий процес: клієнт додає ваш акаунт у свій Meta-застосунок (або ви створюєте застосунок і даєте клієнту роль), генеруєте окремий токен на акаунт і зберігаєте їх ізольовано. Так відкликання одного токена не зачіпає решту клієнтів, а в разі завершення співпраці доступ закривається одним кліком.

Безпека токена: три правила

Access token із permission на insights — це повний доступ до статистики вашого акаунта. Поводитися з ним треба як із паролем:

1. Ніколи не комітьте токен у git. Класична помилка: токен у конфігу, конфіг у публічному репозиторії, через годину його вже знайшли сканери. Тримайте токен у .env, а .env — у .gitignore. У готових продуктах на кшталт Instagram Dashboard це зроблено за замовчуванням: секрети не потрапляють у репозиторій структурно.
2. Не вставляйте токен у сторонні «безкоштовні чекери». Сайти формату «перевір свій токен онлайн» — найпростіший спосіб його злити. Перевіряйте через curl зі свого термінала або через офіційний Access Token Debugger у Meta for Developers.
3. Токен скомпрометований — відкликайте одразу. У налаштуваннях застосунку можна інвалідувати токени і згенерувати нові. Якщо токен світився у скріншоті, логах CI або публічному репозиторії — вважайте його злитим і міняйте, навіть «про всяк випадок».

І окремо про зберігання: якщо ваш дашборд self-hosted, токен лежить на вашому сервері і нікуди не передається. Якщо ж ви віддаєте токен SaaS-сервісу — ви фактично довіряєте статистику свого акаунта чужій інфраструктурі. Це нормальний компроміс, але він має бути усвідомленим.

Підсумок

Весь шлях — Business-акаунт → застосунок у Meta for Developers → use case «Manage messaging & content on Instagram» → permission instagram_business_manage_insights → довгоживучий токен → перевірка через curl — займає 10–15 хвилин, якщо йти по кроках і не плутати сучасний Instagram API зі старим Basic Display. Найчастіша причина проблем — не помилки в коді, а протухлі токени і відсутній permission.

Далі токен можна віддати безкоштовному Instagram Dashboard і отримати повну аналітику без рядка коду. А якщо вашому бізнесу потрібно більше — інтеграція Instagram-даних у власну звітність, наскрізна аналітика чи інші AI-рішення для бізнесу — команда MaxICo Labs допоможе. Почніть із безкоштовного 30-хвилинного AI-аудиту: maxicolabs.com/contact.