Собрать один ролик Instagram Reels вручную несложно. Построить воспроизводимый датасет по сотням публичных авторов труднее: Reels могут исчезать, метрики меняются, URL медиа истекают, а набор видимых полей отличается от публикации к публикации.
В этом руководстве показано, как собирать публичные Reels по имени пользователя с помощью SocQ Instagram Reels API, опрашивать асинхронную задачу, хранить стабильные поля сущностей отдельно от снимков метрик и готовить данные для мониторинга или анализа.
Коротко: отправьте публичные имена пользователей и
results_limitдля каждого из них наPOST /v1/instagram/reels. Сохраните возвращенныйtask_id, опрашивайте эндпоинт задачи и читайте нормализованные записи Reels изdata.results.items. Текущий эндпоинт принимает имена пользователей, а не URL отдельных Reels.
Официальный API Instagram или API публичных Reels?
Официальные API Instagram от Meta — правильный выбор, когда пользователь авторизует поддерживаемый профессиональный аккаунт, а вашему приложению нужны публикация контента, статистика, управление комментариями или другие операции, требующие разрешений.
Это не универсальный эндпоинт для сбора произвольных публичных профилей обычных пользователей. Официальный доступ зависит от типа аккаунта, разрешений, токенов, проверки приложения и выбранного продукта Instagram. Прежде чем проектировать авторизованный сценарий, изучите текущую документацию Instagram Platform.
Используйте SocQ для поддерживаемого сценария чтения публичных данных. Используйте официальные API от Meta для действий с аккаунтом и статистики, требующей разрешений. API публичных данных не дает права игнорировать условия Instagram, права на конфиденциальность или правила интеллектуальной собственности.
Отправка задачи Instagram Reels
Текущий эндпоинт принимает одно или несколько публичных имен пользователей:
curl -X POST "https://api.socq.ai/v1/instagram/reels" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["natgeo", "instagram"],
"results_limit": 100
}'
Нормализуйте имена пользователей перед отправкой:
- Удаляйте начальный
@. - Обрезайте пробелы.
- Преобразуйте URL профилей в имена пользователей на уровне входных данных.
- Удаляйте дубликаты без учета регистра.
- Отклоняйте пустые значения.
results_limit ограничивает число запрашиваемых результатов на одно имя пользователя; он не гарантирует, что у каждого автора есть столько доступных публичных Reels.
Опрос асинхронной задачи
Сохраните возвращенный task_id и опрашивайте:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Статусы queued и running — это нормальное состояние. Используйте экспоненциальную задержку, а не опрос в плотном цикле. Когда задача завершится успешно, читайте data.results.items. Если has_more равно true, запросите следующую страницу с next_cursor.
Надежный воркер должен сохранять:
- ID пакета.
- ID задачи SocQ.
- Отправленные имена пользователей.
- Время отправки и завершения.
- Конечный статус и категорию ошибки.
- Последний обработанный курсор результатов.
Это состояние позволяет воркеру продолжить работу без повторной отправки уже завершенного сбора.
Структура ответа для Reels
Нормализованная запись Reels выглядит примерно так:
{
"id": "3138424916027781494",
"platform": "instagram",
"resource": "reels",
"type": "reel",
"shortcode": "CtjoC2BNsB2",
"url": "https://www.instagram.com/reel/CtjoC2BNsB2/",
"caption": "A public Instagram Reel.",
"author": {
"id": "123",
"username": "natgeo",
"name": "National Geographic",
"url": "https://www.instagram.com/natgeo"
},
"metrics": {
"likes_count": 21904,
"comments_count": 502,
"views_count": 284110,
"plays_count": 284110
},
"media": [],
"duration_seconds": 42,
"audio": {
"title": "Original audio",
"artist": "natgeo"
},
"hashtags": [],
"mentions": [],
"created_at": "2026-07-08T16:05:00",
"collected_at": "2026-07-19T10:00:00",
"extra": {}
}
Используйте id как предпочтительный ключ сущности, а shortcode — как резервный вариант. Сохраняйте url для прослеживаемости. Метрики, медиа, аудио и некоторые поля профиля могут быть недоступны; моделируйте их как допускающие null, а не превращайте отсутствующие значения в ноль или пустые строки.
Храните сущности и снимки метрик отдельно
Идентичность ролика Reels и его метрики меняются с разной скоростью.
Таблица сущностей может хранить:
reel_id
shortcode
canonical_url
author_id
caption
created_at
duration_seconds
audio
first_seen_at
last_seen_at
Таблица снимков может хранить:
reel_id
collected_at
likes_count
comments_count
views_count
plays_count
Так ежедневный мониторинг не создает дубликатов сущностей Reels и при этом сохраняет динамику роста.
Не вычисляйте рост, если метрика отсутствует хотя бы в одном из снимков. Скрытый счетчик — это не ноль. Также не сравнивайте views_count и plays_count так, будто каждый источник определяет их одинаково.
Инкрементальный мониторинг Reels
Простейший надежный мониторинг:
Creator registry
↓
Daily or hourly collection schedule
↓
Async task polling
↓
Schema validation
↓
Upsert Reel entity by id
↓
Append metric snapshot
↓
Alerts and reports
Для каждого автора:
- Собирайте разумное окно недавних публикаций.
- Сортируйте записи по
created_at, если оно доступно. - Перестаньте считать старые повторяющиеся записи новыми находками.
- Выполняйте upsert по ID ролика.
- Добавляйте снимок только при успешном сборе.
- Отслеживайте последний успешный запуск по автору отдельно от отправки задачи.
Ленты Instagram ранжируются, а доступность источника может меняться. Не рассматривайте эндпоинт как гарантированно полный исторический архив.
Пример на Python с пагинацией
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
created = requests.post(
f"{BASE}/instagram/reels",
headers=HEADERS,
json={"usernames": ["natgeo"], "results_limit": 200},
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
break
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
items = task["results"]["items"]
cursor = task["results"].get("next_cursor")
while cursor:
page = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
params={"limit": 100, "cursor": cursor},
timeout=30,
)
page.raise_for_status()
results = page.json()["data"]["results"]
items.extend(results["items"])
cursor = results.get("next_cursor")
В продакшене добавьте ограниченное число повторных попыток для тайм-аутов, 429 и 5xx-ответов, допускающих повтор. Не отправляйте неудавшиеся входные данные повторно автоматически, не проверив категорию ошибки.
Проверка данных Reels перед сохранением
Рекомендуемые проверки:
platformдолжно быть равноinstagram.resourceдолжно быть равноreels.- Должно присутствовать хотя бы одно из полей
id,shortcodeилиurl. author.usernameдолжно совпадать с отправленным автором, если оно доступно.- Счетчики должны быть неотрицательными числами или null.
created_atиcollected_atдолжны разбираться как временные метки.- Элементы медиа нужно рассматривать как ссылки на источник, а не как постоянные ресурсы.
Храните невалидные записи в карантинной таблице вместе с исходной задачей и ошибкой проверки. Молчаливое приведение полей скрывает изменения на стороне источника.
URL медиа — не постоянное хранилище
URL видео, изображений, обложек и аватаров Reels могут быть подписанными, преобразованными, ограниченными по частоте запросов или измененными. Не рассчитывайте, что URL, собранный сегодня, будет работать вечно.
Если продукту нужно долгосрочное хранение медиа:
- Убедитесь, что хранение ресурса разрешено.
- Скачивайте только медиа, необходимые для заявленной цели.
- Записывайте исходный URL и время сбора.
- Применяйте правила хранения и удаления.
- Отдавайте сохраненные медиа безопасным способом.
Если для аналитики нужны только подписи и метрики, хранение больших медиафайлов может добавить затраты и риски, не добавив ценности.
Аккуратно измеряйте эффективность Reels
Полезные производные метрики:
engagement_per_play =
(likes + comments) / plays
daily_play_growth =
(current_plays - previous_plays) / elapsed_days
Вычисляйте метрику, только когда все ее входные данные присутствуют. Сравнивайте авторов в одинаковых окнах и по одинаковому расписанию сбора. Ролик, опубликованный два часа назад, нельзя ранжировать наравне с роликом, который наблюдается две недели, без нормализации по времени.
Публичные счетчики — это видимые снимки, а не проверенная аналитика. Для собственных профессиональных аккаунтов лучшим источником данных об эффективности, требующих разрешений, является официальный Instagram Insights.
Обработка типичных сбоев
| Случай | Рекомендуемая обработка |
|---|---|
| Невалидное имя пользователя | Отклонить до отправки |
| Закрытый аккаунт | Пометить как недоступный; не обходить |
| Переименованный аккаунт | Разрешить вручную или обновить реестр |
| Нет публичных Reels | Сохранить пустое успешное наблюдение |
| Тайм-аут задачи | Повторить опрос до повторной отправки |
| Отсутствующие метрики | Сохранить null |
| Дубликат ролика | Upsert по ID или shortcode |
| Истекший URL медиа | Обновлять, только если сценарий это допускает |
Пустой успешный результат и неудавшаяся задача — разные операционные состояния.
Ответственное использование
- Собирайте только публичные данные, необходимые для законной цели.
- Не обращайтесь к закрытым профилям и не обходите механизмы контроля.
- Избегайте профилирования отдельных людей по чувствительным признакам.
- Соблюдайте запросы на удаление, конфиденциальность и права интеллектуальной собственности.
- Защищайте API-ключи, выгрузки и медиа.
- Изучите условия Instagram и договор с поставщиком.
- Для действий с аккаунтом используйте официальную авторизацию Meta.
SocQ предоставляет технический процесс сбора, а не дополнительные права на контент.
FAQ по Instagram Reels API
Может ли SocQ напрямую спарсить один URL ролика Reels?
Текущий эндпоинт Reels принимает публичные имена пользователей, а не URL отдельных Reels. Он возвращает доступные публичные Reels этих авторов.
Возвращает ли эндпоинт видеофайлы?
Он возвращает нормализованные ссылки на публичные медиа, если они доступны. Рассматривайте URL как временные ссылки на источник, а не как постоянные загрузки.
Всегда ли присутствуют счетчики просмотров и воспроизведений?
Нет. Instagram может скрывать или опускать метрики. Сохраняйте отсутствующие значения как null.
Можно ли собирать Reels закрытых аккаунтов?
Нет. Сценарий работы с публичными данными не должен обходить ограничения закрытых аккаунтов.
Как избежать дубликатов Reels?
Используйте публичный ID ролика как предпочтительный ключ, а shortcode — как резервный. Храните метрики в отдельной таблице снимков.
Стоит ли вместо этого использовать официальный API Instagram от Meta?
Используйте официальный API для авторизованных профессиональных аккаунтов, публикации контента, статистики и действий с аккаунтом. Используйте SocQ для поддерживаемого им сценария чтения публичных данных.
INSTAGRAM API
Проверить сценарий на публичном URL Instagram
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для Instagram