InstagramReelsTutorial sulle API

Come estrarre i dati dei Reels di Instagram con un’API

Costruisci un flusso di lavoro di produzione per raccogliere i Reels pubblici di Instagram per nome utente: didascalie, media, audio, metriche visibili, paginazione e istantanee delle metriche.

SocQAggiornato il 19 luglio 20267 min di lettura

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_limit per nome utente a POST /v1/instagram/reels. Salva il task_id restituito, interroga l’endpoint dell’attività e leggi i record normalizzati dei Reels da data.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:

  1. Raccogli una finestra recente ragionevole.
  2. Ordina i record per created_at quando disponibile.
  3. Smetti di trattare come nuove scoperte i vecchi record ripetuti.
  4. Fai l’upsert per ID del Reel.
  5. Aggiungi un’istantanea solo se la raccolta è riuscita.
  6. 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:

  • platform deve essere uguale a instagram.
  • resource deve essere uguale a reels.
  • Deve esistere almeno uno tra id, shortcode e url.
  • author.username dovrebbe corrispondere al creator inviato, quando disponibile.
  • I conteggi devono essere numeri non negativi oppure null.
  • created_at e collected_at devono 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:

  1. Verifica che l’archiviazione dell’asset sia consentita.
  2. Scarica solo i media necessari allo scopo dichiarato.
  3. Registra l’URL originale e il momento della raccolta.
  4. Applica controlli di conservazione ed eliminazione.
  5. 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

CasoGestione consigliata
Nome utente non validoRifiutare prima dell’invio
Account privatoSegnare come non disponibile; non aggirare
Account rinominatoRisolvere manualmente o aggiornare il registro
Nessun Reel pubblicoSalvare un’osservazione riuscita vuota
Timeout dell’attivitàRiprovare l’interrogazione prima di reinviare
Metriche mancantiMantenere null
Reel duplicatoUpsert per ID o shortcode
URL del media scadutoAggiornare 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