Collecter un Reel Instagram à la main est facile. Construire un jeu de données reproductible sur des centaines de créateurs publics est plus difficile : les Reels peuvent disparaître, les métriques évoluent, les URL de médias expirent et les champs visibles diffèrent d’une publication à l’autre.
Ce tutoriel montre comment collecter des Reels publics par nom d’utilisateur avec l’Instagram Reels API de SocQ, interroger l’état de la tâche asynchrone, stocker les champs stables des entités séparément des instantanés de métriques, et préparer les données pour la veille ou l’analyse.
Réponse rapide : envoyez des noms d’utilisateur publics et un
results_limitpar nom d’utilisateur àPOST /v1/instagram/reels. Enregistrez letask_idrenvoyé, interrogez l’endpoint des tâches et lisez les Reels normalisés dansdata.results.items. L’endpoint actuel accepte des noms d’utilisateur, pas des URL de Reels individuels.
API Instagram officielle ou API publique de Reels ?
Les API Instagram officielles de Meta sont le bon choix lorsqu’un utilisateur autorise un compte professionnel pris en charge et que votre application a besoin de publier, d’accéder aux statistiques, de gérer les commentaires ou d’effectuer d’autres opérations soumises à autorisation.
Elles ne constituent pas un endpoint général pour collecter des profils publics grand public quelconques. L’accès officiel dépend du type de compte, des permissions, des jetons, de la validation de l’application et du produit Instagram choisi. Consultez la documentation actuelle de l’Instagram Platform avant de concevoir un workflow autorisé.
Utilisez SocQ pour un workflow de lecture publique pris en charge. Utilisez les API officielles de Meta pour les actions sur un compte et les statistiques soumises à autorisation. Une API de données publiques ne vous autorise pas à ignorer les conditions d’Instagram, les droits liés à la vie privée ni les règles de propriété intellectuelle.
Soumettre une tâche Instagram Reels
L’endpoint actuel accepte un ou plusieurs noms d’utilisateur publics :
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
}'
Normalisez les noms d’utilisateur avant l’envoi :
- Retirez le
@initial. - Supprimez les espaces en début et en fin de valeur.
- Convertissez les URL de profils en noms d’utilisateur dans votre couche d’entrée.
- Dédupliquez sans tenir compte de la casse.
- Rejetez les valeurs vides.
results_limit limite le nombre de résultats demandés par nom d’utilisateur ; il ne garantit pas que chaque créateur dispose d’autant de Reels publics.
Interroger la tâche asynchrone
Enregistrez le task_id renvoyé et interrogez l’état de la tâche :
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Considérez queued et running comme des états normaux. Utilisez un backoff exponentiel plutôt qu’une boucle d’interrogation serrée. Lorsque la tâche aboutit, lisez data.results.items. Si has_more vaut true, demandez la page suivante avec next_cursor.
Un worker robuste doit conserver :
- L’ID du lot.
- L’ID de tâche SocQ.
- Les noms d’utilisateur soumis.
- Les heures de soumission et de fin.
- Le statut final et la catégorie d’erreur.
- Le dernier curseur de résultats traité.
Cet état permet au worker de reprendre sans soumettre à nouveau une collecte terminée.
Comprendre la réponse pour un Reel
Un enregistrement de Reel normalisé ressemble à ceci :
{
"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": {}
}
Utilisez id comme clé d’entité de préférence et shortcode en solution de repli. Conservez url pour la traçabilité. Les métriques, les médias, l’audio et certains champs de profil peuvent être indisponibles : modélisez-les comme nullables plutôt que de convertir les valeurs manquantes en zéro ou en chaînes vides.
Stocker séparément les entités et les instantanés de métriques
L’identité d’un Reel et ses métriques évoluent à des rythmes différents.
Une table d’entités peut stocker :
reel_id
shortcode
canonical_url
author_id
caption
created_at
duration_seconds
audio
first_seen_at
last_seen_at
Une table d’instantanés peut stocker :
reel_id
collected_at
likes_count
comments_count
views_count
plays_count
Cela évite qu’une surveillance quotidienne ne crée des entités Reel en double, tout en conservant l’évolution dans le temps.
Ne calculez pas de croissance lorsque la métrique manque dans l’un des deux instantanés. Un compteur masqué n’est pas égal à zéro. Évitez aussi de comparer views_count et plays_count comme si chaque source les définissait de façon identique.
Construire une surveillance incrémentale des Reels
La surveillance fiable la plus simple :
Creator registry
↓
Daily or hourly collection schedule
↓
Async task polling
↓
Schema validation
↓
Upsert Reel entity by id
↓
Append metric snapshot
↓
Alerts and reports
Pour chaque créateur :
- Collectez une fenêtre récente raisonnable.
- Triez les enregistrements par
created_atlorsqu’il est disponible. - Cessez de traiter les anciens enregistrements répétés comme de nouvelles découvertes.
- Faites un upsert par ID de Reel.
- Ajoutez un instantané uniquement si la collecte a abouti.
- Suivez la dernière exécution réussie du créateur séparément de la soumission des tâches.
Les flux Instagram sont classés et la disponibilité des sources peut changer. L’endpoint ne doit pas être considéré comme une archive historique complète garantie.
Exemple Python avec pagination
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")
En production, ajoutez des nouvelles tentatives bornées pour les délais d’expiration, les erreurs 429 et les réponses 5xx pouvant être retentées. Ne soumettez pas automatiquement à nouveau les entrées en échec sans vérifier la catégorie d’erreur.
Valider les données des Reels avant de les stocker
Contrôles recommandés :
platformdoit être égal àinstagram.resourcedoit être égal àreels.- Au moins un champ parmi
id,shortcodeouurldoit exister. author.usernamedoit correspondre au créateur soumis lorsqu’il est disponible.- Les compteurs doivent être des nombres positifs ou nuls, ou null.
created_atetcollected_atdoivent pouvoir être interprétés comme des horodatages.- Les entrées de médias doivent être traitées comme des références vers la source, pas comme des ressources permanentes.
Conservez les enregistrements invalides dans une table de quarantaine, avec la tâche brute et l’erreur de validation. Une conversion silencieuse des champs masque les changements en amont.
Les URL de médias ne sont pas un stockage permanent
Les URL de vidéos, d’images, de couvertures et d’avatars des Reels peuvent être signées, transformées, soumises à une limite de débit ou modifiées. Ne partez pas du principe qu’une URL collectée aujourd’hui fonctionnera indéfiniment.
Si le produit doit conserver des médias à long terme :
- Vérifiez que le stockage de la ressource est autorisé.
- Ne téléchargez que les médias nécessaires à la finalité déclarée.
- Consignez l’URL d’origine et l’heure de collecte.
- Appliquez des contrôles de conservation et de suppression.
- Diffusez les médias stockés de façon sécurisée.
Si l’analyse n’a besoin que des légendes et des métriques, stocker de gros fichiers multimédias peut ajouter du coût et du risque sans apporter de valeur.
Mesurer avec prudence la performance des Reels
Parmi les métriques dérivées utiles :
engagement_per_play =
(likes + comments) / plays
daily_play_growth =
(current_plays - previous_plays) / elapsed_days
Ne calculez une métrique que si ses entrées sont présentes. Comparez les créateurs avec des fenêtres et des calendriers de collecte cohérents. Un Reel publié il y a deux heures ne doit pas être classé face à un Reel observé pendant deux semaines sans normalisation temporelle.
Les compteurs publics sont des instantanés visibles, pas des statistiques auditées. Pour les comptes professionnels que vous possédez, Instagram Insights officiel est la meilleure source de données de performance soumises à autorisation.
Gérer les cas d’échec courants
| Cas | Traitement recommandé |
|---|---|
| Nom d’utilisateur invalide | Rejeter avant l’envoi |
| Compte privé | Marquer comme indisponible ; ne pas contourner |
| Compte renommé | Résoudre manuellement ou mettre à jour le registre |
| Aucun Reel public | Enregistrer une observation réussie vide |
| Délai d’expiration de la tâche | Réessayer l’interrogation avant de soumettre à nouveau |
| Métriques manquantes | Conserver null |
| Reel en double | Upsert par ID ou shortcode |
| URL de média expirée | Actualiser uniquement si le cas d’usage l’autorise |
Un résultat vide réussi et une tâche en échec sont deux états opérationnels différents.
Usage responsable
- Ne collectez que les données publiques nécessaires à une finalité légitime.
- N’accédez pas aux profils privés et ne contournez pas les contrôles.
- Évitez le profilage individuel de données sensibles.
- Respectez les demandes de suppression, de confidentialité et de propriété intellectuelle.
- Sécurisez les clés API, les exports et les médias.
- Consultez les conditions d’Instagram et votre contrat avec le fournisseur.
- Utilisez l’autorisation officielle de Meta pour les actions sur un compte.
SocQ fournit un workflow technique de collecte, pas des droits supplémentaires sur les contenus.
Instagram Reels API : FAQ
SocQ peut-il scraper directement l’URL d’un Reel ?
L’endpoint Reels actuel accepte des noms d’utilisateur publics, pas des URL de Reels individuels. Il renvoie les Reels publics disponibles pour ces créateurs.
L’endpoint renvoie-t-il des fichiers vidéo ?
Il renvoie des références normalisées vers les médias publics lorsqu’elles sont disponibles. Considérez les URL comme des références temporaires vers la source, pas comme des téléchargements permanents.
Les nombres de vues et de lectures sont-ils toujours présents ?
Non. Instagram peut masquer ou omettre des métriques. Conservez les valeurs manquantes sous forme de null.
Puis-je collecter les Reels d’un compte privé ?
Non. Un workflow de données publiques ne doit pas contourner les contrôles d’un compte privé.
Comment éviter les Reels en double ?
Utilisez l’ID public du Reel comme clé de préférence et le shortcode en solution de repli. Stockez les métriques dans une table d’instantanés distincte.
Dois-je plutôt utiliser l’API Instagram officielle de Meta ?
Utilisez l’API officielle pour les comptes professionnels autorisés, la publication, les statistiques et les actions sur un compte. Utilisez SocQ pour son workflow de lecture publique pris en charge.
INSTAGRAM API
Tester le workflow avec une URL publique Instagram
Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.
Découvrir les API Instagram