Raccogliere a mano un singolo Reel di Instagram è facile. Costruire un dataset ripetibile su centinaia di creator pubblici è più difficile: i Reels possono sparire, le metriche cambiano, gli URL dei media scadono e i campi visibili variano da un post all’altro.
Questo tutorial mostra come raccogliere i Reels pubblici per nome utente con Instagram Reels API di SocQ, interrogare lo stato dell’attività asincrona, archiviare i campi stabili dell’entità separatamente dalle istantanee delle metriche e preparare i dati per il monitoraggio o l’analisi.
Risposta rapida: invia nomi utente pubblici e un
results_limitper nome utente aPOST /v1/instagram/reels. Salva iltask_idrestituito, interroga l’endpoint dell’attività e leggi i record normalizzati dei Reels dadata.results.items. L’endpoint attuale accetta nomi utente, non URL di singoli Reels.
API ufficiale di Instagram o API pubblica per i Reels?
Le API ufficiali di Instagram di Meta sono la scelta giusta quando un utente autorizza un account professionale supportato e la tua applicazione ha bisogno di pubblicazione, insight, gestione dei commenti o altre operazioni basate su permessi.
Non sono un endpoint generico per raccogliere profili consumer pubblici qualsiasi. L’accesso ufficiale dipende dal tipo di account, dai permessi, dai token, dalla revisione dell’app e dal prodotto Instagram scelto. Consulta la documentazione attuale della Instagram Platform prima di progettare un flusso di lavoro autorizzato.
Usa SocQ per un flusso di lettura pubblica supportato. Usa le API ufficiali di Meta per le azioni sull’account e per gli insight basati su permessi. Un’API di dati pubblici non dà il diritto di ignorare i termini di Instagram, i diritti alla privacy o le regole sulla proprietà intellettuale.
Inviare un’attività per i Reels di Instagram
L’endpoint attuale accetta uno o più nomi utente pubblici:
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
}'
Normalizza i nomi utente prima dell’invio:
- Rimuovi la
@iniziale. - Elimina gli spazi superflui.
- Converti gli URL dei profili in nomi utente nel tuo livello di input.
- Deduplica senza distinguere maiuscole e minuscole.
- Rifiuta i valori vuoti.
results_limit limita i risultati richiesti per ogni nome utente; non garantisce che ogni creator abbia a disposizione quel numero di Reels pubblici.
Interrogare lo stato dell’attività asincrona
Salva il task_id restituito e interroga lo stato:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Considera normali gli stati queued e running. Usa un backoff esponenziale invece di interrogare lo stato in un ciclo serrato. Quando l’attività ha successo, leggi data.results.items. Se has_more è true, richiedi la pagina successiva con next_cursor.
Un worker robusto dovrebbe salvare in modo persistente:
- ID del batch.
- ID dell’attività SocQ.
- Nomi utente inviati.
- Orari di invio e di completamento.
- Stato finale e categoria dell’errore.
- Ultimo cursore dei risultati elaborato.
Questo stato permette al worker di riprendere senza reinviare una raccolta già completata.
Capire la risposta dei Reels
Un record normalizzato di un Reel assomiglia a questo:
{
"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": {}
}
Usa id come chiave preferita dell’entità e shortcode come alternativa di riserva. Conserva url per la tracciabilità. Metriche, media, audio e alcuni campi del profilo possono non essere disponibili: modellali come nullable, senza convertire i valori mancanti in zero o in stringhe vuote.
Archiviare entità e istantanee delle metriche separatamente
L’identità di un Reel e le sue metriche cambiano con velocità diverse.
Una tabella delle entità può contenere:
reel_id
shortcode
canonical_url
author_id
caption
created_at
duration_seconds
audio
first_seen_at
last_seen_at
Una tabella delle istantanee può contenere:
reel_id
collected_at
likes_count
comments_count
views_count
plays_count
Così il monitoraggio giornaliero non crea entità Reel duplicate e la crescita nel tempo viene comunque conservata.
Non calcolare la crescita se in una delle due istantanee manca la metrica. Un conteggio nascosto non è zero. Evita anche di confrontare views_count e plays_count come se ogni fonte li definisse nello stesso modo.
Costruire un monitor incrementale dei Reels
Il monitor affidabile più semplice:
Creator registry
↓
Daily or hourly collection schedule
↓
Async task polling
↓
Schema validation
↓
Upsert Reel entity by id
↓
Append metric snapshot
↓
Alerts and reports
Per ogni creator:
- Raccogli una finestra recente ragionevole.
- Ordina i record per
created_atquando disponibile. - Smetti di trattare come nuove scoperte i vecchi record ripetuti.
- Fai l’upsert per ID del Reel.
- Aggiungi un’istantanea solo se la raccolta è riuscita.
- Tieni traccia dell’ultima esecuzione riuscita del creator separatamente dall’invio dell’attività.
I feed di Instagram sono ordinati per rilevanza e la disponibilità delle fonti può cambiare. L’endpoint non va considerato un archivio storico completo garantito.
Esempio in Python con paginazione
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")
In produzione, aggiungi nuovi tentativi limitati per timeout, 429 e risposte 5xx ripetibili. Non reinviare automaticamente gli input falliti senza controllare la categoria dell’errore.
Convalidare i dati dei Reels prima dell’archiviazione
Controlli consigliati:
platformdeve essere uguale ainstagram.resourcedeve essere uguale areels.- Deve esistere almeno uno tra
id,shortcodeeurl. author.usernamedovrebbe corrispondere al creator inviato, quando disponibile.- I conteggi devono essere numeri non negativi oppure null.
created_atecollected_atdevono essere interpretabili come timestamp.- Le voci dei media vanno trattate come riferimenti alla fonte, non come asset permanenti.
Conserva i record non validi in una tabella di quarantena, insieme all’attività grezza e all’errore di validazione. Forzare silenziosamente i tipi dei campi nasconde i cambiamenti a monte.
Gli URL dei media non sono un’archiviazione permanente
Gli URL di video, immagini, copertine e avatar dei Reels possono essere firmati, trasformati, soggetti a limiti di frequenza o modificati. Non dare per scontato che un URL raccolto oggi funzioni per sempre.
Se il prodotto ha bisogno di conservare i media a lungo termine:
- Verifica che l’archiviazione dell’asset sia consentita.
- Scarica solo i media necessari allo scopo dichiarato.
- Registra l’URL originale e il momento della raccolta.
- Applica controlli di conservazione ed eliminazione.
- Servi i media archiviati in modo sicuro.
Se per le analisi bastano didascalie e metriche, archiviare file multimediali di grandi dimensioni può aggiungere costi e rischi senza aggiungere valore.
Misurare con attenzione le prestazioni dei Reels
Metriche derivate utili:
engagement_per_play =
(likes + comments) / plays
daily_play_growth =
(current_plays - previous_plays) / elapsed_days
Calcola una metrica solo quando i suoi input sono presenti. Confronta i creator usando finestre e pianificazioni di raccolta coerenti. Un Reel pubblicato due ore fa non dovrebbe essere messo in classifica insieme a uno osservato da due settimane senza una normalizzazione temporale.
I conteggi pubblici sono istantanee visibili, non analytics verificati. Per gli account professionali di tua proprietà, Instagram Insights ufficiale è la fonte migliore per i dati di performance basati su permessi.
Gestire i casi di errore più comuni
| Caso | Gestione consigliata |
|---|---|
| Nome utente non valido | Rifiutare prima dell’invio |
| Account privato | Segnare come non disponibile; non aggirare |
| Account rinominato | Risolvere manualmente o aggiornare il registro |
| Nessun Reel pubblico | Salvare un’osservazione riuscita vuota |
| Timeout dell’attività | Riprovare l’interrogazione prima di reinviare |
| Metriche mancanti | Mantenere null |
| Reel duplicato | Upsert per ID o shortcode |
| URL del media scaduto | Aggiornare solo se il caso d’uso lo consente |
Un risultato riuscito ma vuoto e un’attività fallita sono stati operativi diversi.
Uso responsabile
- Raccogli solo i dati pubblici necessari per uno scopo legittimo.
- Non accedere a profili privati e non aggirare i controlli.
- Evita la profilazione di singole persone su aspetti sensibili.
- Rispetta le richieste di eliminazione, privacy e proprietà intellettuale.
- Proteggi chiavi API, esportazioni e media.
- Consulta i termini di Instagram e il contratto con il tuo provider.
- Usa l’autorizzazione ufficiale di Meta per le azioni sugli account.
SocQ fornisce un flusso di raccolta tecnico, non diritti aggiuntivi sui contenuti.
Domande frequenti (FAQ)
SocQ può estrarre direttamente l’URL di un singolo Reel?
L’endpoint Reels attuale accetta nomi utente pubblici, non URL di singoli Reels. Restituisce i Reels pubblici disponibili per quei creator.
L’endpoint restituisce i file video?
Restituisce riferimenti normalizzati ai media pubblici, quando disponibili. Considera gli URL come riferimenti temporanei alla fonte, non come download permanenti.
I conteggi di visualizzazioni e riproduzioni sono sempre presenti?
No. Instagram può nascondere o omettere le metriche. Mantieni i valori mancanti come null.
Posso raccogliere i Reels degli account privati?
No. Un flusso di lavoro basato su dati pubblici non deve aggirare i controlli degli account privati.
Come evito i Reels duplicati?
Usa l’ID pubblico del Reel come chiave preferita e lo shortcode come alternativa di riserva. Archivia le metriche in una tabella di istantanee separata.
Dovrei usare invece l’API ufficiale di Instagram di Meta?
Usa l’API ufficiale per gli account professionali autorizzati, la pubblicazione, gli insight e le azioni sugli account. Usa SocQ per il suo flusso di lettura pubblica supportato.
INSTAGRAM API
Prova il flusso di lavoro con un URL pubblico di Instagram
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di Instagram