InstagramReelsTutorial de API

Cómo extraer datos de Reels de Instagram con una API

Construya un flujo de trabajo de producción para recopilar Reels públicos de Instagram por nombre de usuario, con descripciones, medios, audio, métricas visibles, paginación e instantáneas de métricas.

SocQActualizado el 19 de julio de 20268 min de lectura

Recopilar un solo Reel de Instagram a mano es fácil. Construir un conjunto de datos repetible con cientos de creadores públicos es más difícil: los Reels pueden desaparecer, las métricas cambian, las URL de los medios vencen y los campos visibles varían de una publicación a otra.

Este tutorial muestra cómo recopilar Reels públicos por nombre de usuario con SocQ Instagram Reels API, consultar la tarea asíncrona, guardar los campos estables de la entidad por separado de las instantáneas de métricas y preparar los datos para el monitoreo o el análisis.

Respuesta rápida: envíe nombres de usuario públicos y un results_limit por nombre de usuario a POST /v1/instagram/reels. Guarde el task_id devuelto, consulte el endpoint de tareas y lea los registros normalizados de Reels en data.results.items. El endpoint actual acepta nombres de usuario, no URL de Reels individuales.

¿API oficial de Instagram o una API pública de Reels?

Las API oficiales de Instagram de Meta son la opción correcta cuando un usuario autoriza una cuenta profesional compatible y su aplicación necesita publicar, obtener estadísticas, administrar comentarios u otras operaciones con permisos.

No son un endpoint general para recopilar perfiles de consumidores públicos arbitrarios. El acceso oficial depende del tipo de cuenta, los permisos, los tokens, la revisión de la aplicación y el producto de Instagram seleccionado. Revise la documentación vigente de Instagram Platform antes de diseñar un flujo autorizado.

Use SocQ para un flujo público de solo lectura compatible. Use las API oficiales de Meta para las acciones de la cuenta y las estadísticas con permisos. Una API de datos públicos no otorga permiso para ignorar los términos de Instagram, los derechos de privacidad ni las normas de propiedad intelectual.

Enviar una tarea de Reels de Instagram

El endpoint actual acepta uno o varios nombres de usuario públicos:

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
  }'

Normalice los nombres de usuario antes de enviarlos:

  • Quite el @ inicial.
  • Elimine los espacios en blanco sobrantes.
  • Convierta las URL de perfil en nombres de usuario en su capa de entrada.
  • Elimine duplicados sin distinguir mayúsculas de minúsculas.
  • Rechace los valores vacíos.

results_limit limita los resultados solicitados por nombre de usuario; no garantiza que cada creador tenga esa cantidad de Reels públicos disponibles.

Consultar la tarea asíncrona

Guarde el task_id devuelto y consulte el estado:

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Considere normales los estados queued y running. Use retroceso exponencial en lugar de consultar en un ciclo ajustado. Cuando la tarea termina con éxito, lea data.results.items. Si has_more es true, solicite la página siguiente con next_cursor.

Un worker robusto debe conservar:

  • El ID del lote.
  • El ID de la tarea de SocQ.
  • Los nombres de usuario enviados.
  • Las horas de envío y de finalización.
  • El estado terminal y la categoría del error.
  • El último cursor de resultados procesado.

Ese estado permite que el worker se reanude sin volver a enviar una recopilación ya completada.

Cómo interpretar la respuesta de Reels

Un registro normalizado de Reel se parece a esto:

{
  "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": {}
}

Use id como clave preferida de la entidad y shortcode como alternativa de respaldo. Conserve url para la trazabilidad. Las métricas, los medios, el audio y algunos campos del perfil pueden no estar disponibles; modélelos como valores que admiten null en lugar de convertir los valores faltantes en cero o en cadenas vacías.

Guardar las entidades y las instantáneas de métricas por separado

La identidad de un Reel y sus métricas cambian a ritmos distintos.

Una tabla de entidades puede guardar:

reel_id
shortcode
canonical_url
author_id
caption
created_at
duration_seconds
audio
first_seen_at
last_seen_at

Una tabla de instantáneas puede guardar:

reel_id
collected_at
likes_count
comments_count
views_count
plays_count

Así, el monitoreo diario no crea entidades de Reel duplicadas y se conserva el crecimiento a lo largo del tiempo.

No calcule el crecimiento cuando a alguna de las dos instantáneas le falte la métrica. Un conteo oculto no es cero. Evite también comparar views_count y plays_count como si todas las fuentes los definieran de la misma manera.

Construir un monitor incremental de Reels

El monitor confiable más sencillo:

Creator registry
      ↓
Daily or hourly collection schedule
      ↓
Async task polling
      ↓
Schema validation
      ↓
Upsert Reel entity by id
      ↓
Append metric snapshot
      ↓
Alerts and reports

Para cada creador:

  1. Recopile una ventana reciente razonable.
  2. Ordene los registros por created_at cuando esté disponible.
  3. Deje de tratar los registros antiguos repetidos como descubrimientos nuevos.
  4. Haga upsert por ID del Reel.
  5. Agregue una instantánea solo cuando la recopilación haya tenido éxito.
  6. Registre la última ejecución exitosa del creador por separado del envío de la tarea.

Los feeds de Instagram están clasificados y la disponibilidad de las fuentes puede cambiar. El endpoint no debe considerarse un archivo histórico completo garantizado.

Ejemplo en Python con paginación

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 producción, agregue reintentos acotados para los tiempos de espera agotados, los errores 429 y las respuestas 5xx que admiten reintento. No vuelva a enviar automáticamente las entradas fallidas sin revisar la categoría del error.

Validar los datos de Reels antes de guardarlos

Verificaciones recomendadas:

  • platform debe ser igual a instagram.
  • resource debe ser igual a reels.
  • Debe existir al menos uno de id, shortcode o url.
  • author.username debería coincidir con el creador enviado, cuando esté disponible.
  • Los conteos deben ser números no negativos o null.
  • created_at y collected_at deben poder interpretarse como marcas de tiempo.
  • Las entradas de medios deben tratarse como referencias de origen, no como recursos permanentes.

Conserve los registros no válidos en una tabla de cuarentena junto con la tarea sin procesar y el error de validación. Forzar la conversión de campos en silencio oculta los cambios de origen.

Las URL de los medios no son almacenamiento permanente

Las URL del video, la imagen, la portada y el avatar de un Reel pueden estar firmadas, transformadas, limitadas o cambiar. No suponga que una URL recopilada hoy funcionará para siempre.

Si el producto necesita retener medios a largo plazo:

  1. Confirme que está permitido guardar el recurso.
  2. Descargue solo los medios necesarios para el propósito declarado.
  3. Registre la URL original y la hora de recopilación.
  4. Aplique controles de retención y eliminación.
  5. Entregue los medios guardados de forma segura.

Si el análisis solo necesita descripciones y métricas, guardar archivos de medios grandes puede añadir costo y riesgo sin aportar valor.

Cómo medir el rendimiento de los Reels con cuidado

Entre las métricas derivadas útiles se incluyen:

engagement_per_play =
  (likes + comments) / plays

daily_play_growth =
  (current_plays - previous_plays) / elapsed_days

Calcule una métrica solo cuando estén presentes sus datos de entrada. Compare a los creadores con ventanas y calendarios de recopilación consistentes. Un Reel publicado hace dos horas no debe clasificarse frente a uno observado durante dos semanas sin normalizar el tiempo.

Los conteos públicos son instantáneas visibles, no analítica auditada. Para las cuentas profesionales propias, Instagram Insights oficial es la mejor fuente de datos de rendimiento con permisos.

Manejar los casos de falla comunes

CasoManejo recomendado
Nombre de usuario no válidoRechazar antes de enviar
Cuenta privadaMarcar como no disponible; no eludir
Cuenta con nombre cambiadoResolver manualmente o actualizar el registro
Sin Reels públicosGuardar una observación exitosa vacía
Tiempo de espera agotado de la tareaReintentar la consulta antes de volver a enviar
Métricas faltantesConservar null
Reel duplicadoHacer upsert por ID o shortcode
URL de medios vencidaActualizar solo cuando el caso de uso lo permita

Un resultado vacío exitoso y una tarea fallida son estados operativos distintos.

Uso responsable

  • Recopile solo los datos públicos necesarios para un propósito legítimo.
  • No acceda a perfiles privados ni eluda controles.
  • Evite la creación de perfiles sensibles de personas.
  • Respete las solicitudes de eliminación, privacidad y propiedad intelectual.
  • Proteja las claves de API, las exportaciones y los medios.
  • Revise los términos de Instagram y el contrato con su proveedor.
  • Use la autorización oficial de Meta para las acciones de la cuenta.

SocQ ofrece un flujo técnico de recopilación, no derechos adicionales sobre el contenido.

Instagram Reels API: preguntas frecuentes (FAQ)

¿SocQ puede extraer directamente la URL de un solo Reel?

El endpoint actual de Reels acepta nombres de usuario públicos, no URL de Reels individuales. Devuelve los Reels públicos disponibles de esos creadores.

¿El endpoint devuelve archivos de video?

Devuelve referencias a medios públicos normalizadas cuando están disponibles. Trate las URL como referencias de origen temporales, no como descargas permanentes.

¿Los conteos de vistas y de reproducciones siempre están presentes?

No. Instagram puede ocultar u omitir métricas. Conserve los valores faltantes como null.

¿Puedo recopilar Reels de cuentas privadas?

No. Un flujo de datos públicos no debe eludir los controles de las cuentas privadas.

¿Cómo evito los Reels duplicados?

Use el ID público del Reel como clave preferida y el shortcode como alternativa de respaldo. Guarde las métricas en una tabla de instantáneas independiente.

¿Debería usar mejor la API oficial de Instagram de Meta?

Use la API oficial para cuentas profesionales autorizadas, publicación, estadísticas y acciones de la cuenta. Use SocQ para su flujo público de solo lectura compatible.

INSTAGRAM API

Probar el flujo de trabajo con una URL pública de Instagram

Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.

Ver las API de Instagram