Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

API de Instagram en Python y Node.js: ejemplos funcionales

La API de Instagram solo necesita HTTPS, así que requests de Python y el fetch integrado de Node.js bastan: POST /<IG_ID>/media y después media_publish publican, /<IG_MEDIA_ID>/comments y /<IG_COMMENT_ID>/replies leen y responden comentarios, /insights devuelve métricas, y un webhook se verifica con un HMAC-SHA256 del cuerpo sin procesar. Cada error trae un código y un subcódigo que deciden si reintentar la petición puede ayudar.

easyCoexistence ejecuta las mismas tareas como herramientas MCP para Claude, ChatGPT o tu propio agente, con el token guardado de su lado: publish_instagram_post, reply_to_comment, get_social_insights y set_social_webhook_destination, sobre la API oficial de Meta.

v26.0

La versión más reciente de la Graph API, presentada el 29 de julio de 2026; la v25.0 sigue disponible hasta el 29 de julio de 2028.

Once a minute

Con qué frecuencia Meta sugiere revisar el status_code de un contenedor de video, durante no más de 5 minutos.

50

El máximo de comentarios que devuelve una petición GET /<IG_MEDIA_ID>/comments; las respuestas solo llegan mediante expansión de campos.

2207008

Un error temporal de publicación, que Meta indica reintentar 1 o 2 veces en un plazo de 30 segundos a 2 minutos.

sha256=

El prefijo de X-Hub-Signature-256, antes del HMAC-SHA256 del payload con el app secret como clave.

¿Qué necesitan los ejemplos?

Un entorno de ejecución, un token y cuatro valores. Los ejemplos llaman a la API de Instagram con Instagram Login en graph.instagram.com; una app de Unified Login usa las mismas rutas con el ID de la cuenta, en el host Graph de Facebook Login y con su token de Business Integration System User. Python necesita el paquete requests, además de Flask para el webhook, y Node.js necesita la versión 18 o posterior para su fetch integrado.

  • GRAPH: https://graph.instagram.com/v26.0, el host y la versión de la API.
  • IG_ID: el ID de la cuenta profesional, el user_id que devuelve GET /me.
  • TOKEN: un token de acceso de usuario de Instagram de larga duración, guardado en el servidor.
  • APP_SECRET y VERIFY_TOKEN: para verificar las peticiones del webhook.

¿Cómo llamar a la API y gestionar errores en Python?

Mediante un único helper, que comparten los ejemplos de Python de abajo. Envía el token como access_token, lanza MetaError con el código, el subcódigo y el fbtrace_id de Meta, y reintenta solo lo que Meta llama temporal: los códigos 1 y 2, los códigos de limitación 4, 17 y 80002, y los subcódigos 2207001, 2207003, 2207008 y 2207032. El código 4 con subcódigo 2207051 indica sospecha de spam, así que se detiene de inmediato.

Python: the shared helper (requests)
import json
import time

import requests

GRAPH = "https://graph.instagram.com/v26.0"
IG_ID = "<IG_ID>"  # user_id from GET /me
TOKEN = "<TOKEN>"  # long-lived Instagram User access token, server side only

RETRY_CODES = {1, 2, 4, 17, 80002}
RETRY_SUBCODES = {2207001, 2207003, 2207008, 2207032}


class MetaError(Exception):
    def __init__(self, error: dict, status: int):
        super().__init__(error.get("message", f"HTTP {status}"))
        self.code = error.get("code")
        self.subcode = error.get("error_subcode")
        self.fbtrace_id = error.get("fbtrace_id")  # log it: Meta support asks for it

    @property
    def needs_new_token(self) -> bool:
        return self.code in (102, 190)

    @property
    def retryable(self) -> bool:
        if self.subcode == 2207051:  # code 4 with this subcode is suspected spam: stop
            return False
        return self.code in RETRY_CODES or self.subcode in RETRY_SUBCODES


def wait_seconds(resp) -> int:
    """estimated_time_to_regain_access from X-Business-Use-Case-Usage, at least 60 s."""
    try:
        usage = json.loads(resp.headers.get("X-Business-Use-Case-Usage", "{}"))
        minutes = max(e.get("estimated_time_to_regain_access", 0) for v in usage.values() for e in v)
    except (ValueError, AttributeError, TypeError):
        minutes = 0
    return max(60, int(minutes) * 60)


def graph(method: str, path: str, attempts: int = 3, **params) -> dict:
    if attempts < 1:
        raise ValueError("attempts must be at least 1")
    params["access_token"] = TOKEN
    for attempt in range(1, attempts + 1):
        resp = requests.request(method, f"{GRAPH}/{path}", params=params, timeout=30)
        try:
            data = resp.json()
        except ValueError:
            data = {}
        if resp.ok and "error" not in data:
            return data
        err = MetaError(data.get("error", {}), resp.status_code)
        if not err.retryable or attempt == attempts:
            raise err
        time.sleep(wait_seconds(resp))

¿Cómo llamar a la API y gestionar errores en Node.js?

Con el mismo helper para Node.js 18 o posterior, usando fetch y sin dependencias. Una llamada limitada espera el estimated_time_to_regain_access, los minutos que Meta informa en la cabecera X-Business-Use-Case-Usage, o 60 segundos si no existe, ya que Meta cuenta las llamadas hechas mientras está limitado. needsNewToken marca los códigos 190 y 102, que ningún reintento puede corregir.

Node.js: the shared helper (fetch, ES module)
const GRAPH = "https://graph.instagram.com/v26.0";
const IG_ID = process.env.IG_ID; // user_id from GET /me
const TOKEN = process.env.TOKEN; // long-lived Instagram User access token, server side only

const RETRY_CODES = new Set([1, 2, 4, 17, 80002]);
const RETRY_SUBCODES = new Set([2207001, 2207003, 2207008, 2207032]);

export class MetaError extends Error {
  constructor(error, status) {
    super(error.message ?? `HTTP ${status}`);
    this.code = error.code;
    this.subcode = error.error_subcode;
    this.fbtraceId = error.fbtrace_id; // log it: Meta support asks for it
  }
  get needsNewToken() {
    return this.code === 190 || this.code === 102;
  }
  get retryable() {
    if (this.subcode === 2207051) return false; // code 4 with this subcode is suspected spam: stop
    return RETRY_CODES.has(this.code) || RETRY_SUBCODES.has(this.subcode);
  }
}

export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// estimated_time_to_regain_access from X-Business-Use-Case-Usage, at least 60 s
function waitMs(res) {
  try {
    const usage = JSON.parse(res.headers.get("x-business-use-case-usage") ?? "{}");
    const minutes = Math.max(0, ...Object.values(usage).flat().map((e) => e.estimated_time_to_regain_access ?? 0));
    return Math.max(60, minutes * 60) * 1000;
  } catch {
    return 60_000;
  }
}

export async function graph(method, path, params = {}, attempts = 3) {
  const url = new URL(`${GRAPH}/${path}`);
  for (const [key, value] of Object.entries({ ...params, access_token: TOKEN })) {
    url.searchParams.set(key, String(value));
  }
  for (let attempt = 1; attempt <= attempts; attempt++) {
    const res = await fetch(url, { method });
    const data = await res.json().catch(() => ({}));
    if (res.ok && !data.error) return data;
    const err = new MetaError(data.error ?? {}, res.status);
    if (!err.retryable || attempt === attempts) throw err;
    await sleep(waitMs(res));
  }
  throw new Error("attempts must be at least 1");
}

¿Cómo publicar una foto y un Reel en Python?

Ambos siguen el flujo de contenedor. Un contenedor de foto está listo al instante, así que media_publish va justo después. El video de un Reel se procesa primero: la función revisa el status_code una vez por minuto durante hasta 5 minutos, como sugiere Meta, publica al recibir FINISHED y se detiene con ERROR o EXPIRED. Las imágenes deben ser JPEG y el medio tiene que estar en una URL pública.

Python: a photo and a Reel
# Uses graph(), IG_ID and time from the helper above
def publish_photo(image_url: str, caption: str) -> str:
    """A JPEG at a public URL: create the container, then publish it."""
    container = graph("POST", f"{IG_ID}/media", image_url=image_url, caption=caption)
    return graph("POST", f"{IG_ID}/media_publish", creation_id=container["id"])["id"]


def publish_reel(video_url: str, caption: str) -> str:
    """A Reel: publish once Meta has processed the video, checking once a minute."""
    cid = graph("POST", f"{IG_ID}/media", media_type="REELS", video_url=video_url, caption=caption)["id"]
    for _ in range(5):  # Meta: once a minute, for no more than 5 minutes
        time.sleep(60)
        status = graph("GET", cid, fields="status_code")["status_code"]
        if status == "FINISHED":
            return graph("POST", f"{IG_ID}/media_publish", creation_id=cid)["id"]
        if status in ("ERROR", "EXPIRED"):
            raise RuntimeError(f"Container {cid} ended as {status}")
    raise TimeoutError(f"Container {cid} is still processing: check it again later")

¿Cómo publicar una foto y un Reel en Node.js?

Las mismas dos funciones, cada una devuelve el nuevo ID del medio. Un contenedor que sigue en IN_PROGRESS tras cinco revisiones sigue siendo válido hasta 24 horas después de su creación, así que el error indica volver a comprobarlo más tarde, lo que evita crear un segundo contenedor contra el límite de 400 al día de la cuenta.

Node.js: a photo and a Reel
// Uses graph(), sleep() and IG_ID from the helper above
export async function publishPhoto(imageUrl, caption) {
  const { id } = await graph("POST", `${IG_ID}/media`, { image_url: imageUrl, caption });
  return (await graph("POST", `${IG_ID}/media_publish`, { creation_id: id })).id;
}

export async function publishReel(videoUrl, caption) {
  const { id } = await graph("POST", `${IG_ID}/media`, { media_type: "REELS", video_url: videoUrl, caption });
  for (let check = 0; check < 5; check++) {
    await sleep(60_000); // Meta: once a minute, for no more than 5 minutes
    const { status_code: status } = await graph("GET", id, { fields: "status_code" });
    if (status === "FINISHED") return (await graph("POST", `${IG_ID}/media_publish`, { creation_id: id })).id;
    if (status === "ERROR" || status === "EXPIRED") throw new Error(`Container ${id} ended as ${status}`);
  }
  throw new Error(`Container ${id} is still processing: check it again later`);
}

¿Cómo leer comentarios y responder en Python?

GET /<IG_MEDIA_ID>/comments devuelve los comentarios de primer nivel, del más reciente al más antiguo, hasta 50 por petición, y POST /<IG_COMMENT_ID>/replies publica una respuesta pública a uno de ellos. La función pide a un callback tuyo el texto de cada respuesta y omite los comentarios para los que no devuelve nada. Los comentarios ocultos no pueden recibir respuesta, y una respuesta a una respuesta cae en el comentario de primer nivel.

Python: read comments and reply
# Uses graph() from the helper above
def reply_to_comments(media_id: str, write_reply) -> int:
    """Reply in public to each comment write_reply returns text for."""
    page = graph("GET", f"{media_id}/comments", fields="id,text,username,timestamp")
    sent = 0
    for comment in page.get("data", []):
        text = write_reply(comment)
        if text:
            graph("POST", f"{comment['id']}/replies", message=text)
            sent += 1
    return sent


# Example: reply to questions about price
reply_to_comments("<IG_MEDIA_ID>", lambda c: "Prices are in our bio link." if "price" in c["text"].lower() else None)

¿Cómo leer comentarios y responder en Node.js?

El mismo bucle en Node.js. Ambas llamadas usan instagram_business_basic e instagram_business_manage_comments, y el campo username necesita el segundo. Para responder en privado, POST /<IG_ID>/messages con recipient.comment_id envía al autor del comentario un mensaje directo, dentro de los 7 días posteriores al comentario, y un seguimiento espera hasta que responda.

Node.js: read comments and reply
// Uses graph() from the helper above
// Reply in public to each comment writeReply returns text for
export async function replyToComments(mediaId, writeReply) {
  const { data = [] } = await graph("GET", `${mediaId}/comments`, { fields: "id,text,username,timestamp" });
  let sent = 0;
  for (const comment of data) {
    const text = writeReply(comment);
    if (text) {
      await graph("POST", `${comment.id}/replies`, { message: text });
      sent++;
    }
  }
  return sent;
}

// Example: reply to questions about price
await replyToComments("<IG_MEDIA_ID>", (c) => (/price/i.test(c.text) ? "Prices are in our bio link." : null));

¿Cómo leer métricas en Python?

Las métricas de cuenta usan period=day con metric_type=total_value, y cada métrica informa después total_value.value; las métricas de una publicación informan values[0].value. El ejemplo pide reach, views y accounts_engaged en la cuenta, y reach, views, likes, comments, saved y shares en una publicación o Reel, que la referencia de Meta lista para ambos. Una métrica sin datos se omite en lugar de devolverse como 0.

Python: account and post insights
# Uses graph() and IG_ID from the helper above
def account_insights() -> dict:
    """Reach, views and accounts engaged over the last 24 hours."""
    data = graph("GET", f"{IG_ID}/insights", metric="reach,views,accounts_engaged",
                 period="day", metric_type="total_value")["data"]
    return {m["name"]: m["total_value"]["value"] for m in data}


def post_insights(media_id: str) -> dict:
    """Totals for one post or Reel."""
    data = graph("GET", f"{media_id}/insights", metric="reach,views,likes,comments,saved,shares")["data"]
    return {m["name"]: m["values"][0]["value"] for m in data}

¿Cómo leer métricas en Node.js?

Las mismas dos peticiones en Node.js, cada una devuelve un objeto indexado por nombre de métrica. Ninguna envía un desglose: Meta advierte que pedir uno que una métrica no admite hace fallar la petición con un error desconocido, y que los datos de métricas pueden retrasarse hasta 48 horas, así que vuelve a leer las publicaciones recientes más tarde.

Node.js: account and post insights
// Uses graph() and IG_ID from the helper above
// Reach, views and accounts engaged over the last 24 hours
export async function accountInsights() {
  const { data } = await graph("GET", `${IG_ID}/insights`, {
    metric: "reach,views,accounts_engaged",
    period: "day",
    metric_type: "total_value",
  });
  return Object.fromEntries(data.map((m) => [m.name, m.total_value?.value]));
}

// Totals for one post or Reel
export async function postInsights(mediaId) {
  const { data } = await graph("GET", `${mediaId}/insights`, { metric: "reach,views,likes,comments,saved,shares" });
  return Object.fromEntries(data.map((m) => [m.name, m.values?.[0]?.value]));
}

¿Cómo verificar un webhook en Python?

Con Flask, en dos métodos sobre una misma ruta. El GET responde a la petición de verificación de Meta: cuando hub.mode es subscribe y hub.verify_token coincide, devuelve hub.challenge como texto plano, y un 403 en caso contrario. El POST calcula sha256= más el HMAC-SHA256 del cuerpo sin procesar con el app secret, lo compara con X-Hub-Signature-256 en tiempo constante y responde 200 antes de que empiece cualquier trabajo lento.

Python: webhook verification and signature check (Flask)
import hashlib
import hmac
import json
import os
from queue import Queue

from flask import Flask, abort, request

app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
jobs: Queue = Queue()  # swap for your own job queue


@app.get("/webhooks/instagram")
def verify():
    """Meta's verification request: send hub.challenge back when the token matches."""
    args = request.args
    if args.get("hub.mode") == "subscribe" and args.get("hub.verify_token") == VERIFY_TOKEN:
        return args.get("hub.challenge", ""), 200, {"Content-Type": "text/plain"}
    abort(403)


@app.post("/webhooks/instagram")
def receive():
    """An event: check X-Hub-Signature-256 over the raw bytes, then answer at once."""
    raw = request.get_data()
    expected = b"sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest().encode()
    if not hmac.compare_digest(expected, request.headers.get("X-Hub-Signature-256", "").encode()):
        abort(401)
    for entry in json.loads(raw).get("entry", []):
        jobs.put(entry)  # slow work happens elsewhere; Meta wants a quick 200
    return "", 200

¿Cómo verificar un webhook en Node.js?

Con el módulo http integrado y sin framework. El cuerpo se recoge como bytes sin procesar antes de que nada lo analice, porque un cuerpo analizado y vuelto a serializar ya no coincide con la firma que calculó Meta. Meta reintenta una notificación fallida durante hasta 36 horas, así que el manejador también debe omitir los eventos que ya haya procesado.

Node.js: webhook verification and signature check (node:http)
import crypto from "node:crypto";
import http from "node:http";

const { VERIFY_TOKEN, APP_SECRET } = process.env;
const PATH = "/webhooks/instagram";
const jobs = []; // swap for your own job queue

http
  .createServer((req, res) => {
    const url = new URL(req.url, "http://localhost");
    if (url.pathname !== PATH) return res.writeHead(404).end();

    if (req.method === "GET") {
      // Meta's verification request: send hub.challenge back when the token matches
      const ok =
        url.searchParams.get("hub.mode") === "subscribe" &&
        url.searchParams.get("hub.verify_token") === VERIFY_TOKEN;
      return res
        .writeHead(ok ? 200 : 403, { "Content-Type": "text/plain" })
        .end(ok ? url.searchParams.get("hub.challenge") ?? "" : "");
    }

    const chunks = [];
    req.on("data", (chunk) => chunks.push(chunk));
    req.on("end", () => {
      const raw = Buffer.concat(chunks); // the exact bytes Meta signed
      const expected = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
      const given = Buffer.from(req.headers["x-hub-signature-256"] ?? "");
      if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
        return res.writeHead(401).end();
      }
      res.writeHead(200).end(); // answer first, work after
      try {
        for (const entry of JSON.parse(raw.toString("utf8")).entry ?? []) jobs.push(entry);
      } catch {
        // not JSON: nothing to queue
      }
    });
  })
  .listen(3000);

¿Qué errores de Meta debe reintentar el código?

Solo los temporales, porque los demás devuelven la misma respuesta hasta que algo cambie: el archivo, la URL, un permiso o el estado de la cuenta. Las referencias de errores de Meta indican la acción para cada código que distinguen los helpers de arriba:

1, 2Temporary or downtime: wait, then retry
4, 17, 80002Throttling: wait for estimated_time_to_regain_access, then retry
4 with 2207051Suspected spam: stop, since a retry repeats the action
2207001, 2207003, 2207032Server error, download timeout or failed container: try again
2207008Container briefly missing: retry 1 to 2 times within 2 minutes
190, 102Token expired or invalid: refresh it while valid, or sign in again
10, 200 to 299Permission missing or removed: request it at sign-in
25 with 2207050Account restricted: the owner acts in the Instagram app
9 with 2207042Daily publishing limit: try again the next day
9004 with 2207052Media not fetched from the URL: fix the link

¿Cómo ejecutar el mismo código con las credenciales de easyCoexistence?

No puedes ejecutarlo con el token de easyCoexistence: los tokens de Instagram nunca se entregan (términos de Meta), así que get_social_credentials y GET /api/v1/channels/:id?credentials=1 de la Partner API devuelven el ID de la cuenta y la base de la API sin token. En su lugar, las mismas tareas se ejecutan como herramientas MCP, a través de Claude, ChatGPT u otro cliente MCP, y los helpers anteriores funcionan sin cambios con un token de tu propia app de Meta.

What get_social_credentials returns for an Instagram account
{
  "platform": "instagram",
  "graph_api_base": "https://graph.instagram.com/<VERSION>",
  "account_id_on_meta": "<IG_ID>",
  "access_token": null,
  "token_note": "Meta's terms do not allow handing this account's access token to other apps, so it is not shown. ..."
}

¿Cómo hacer las mismas tareas mediante el conector MCP?

Pidiéndoselo al asistente o llamando tú mismo a las herramientas. publish_instagram_post crea y publica el contenedor, esperando mientras se procesa un video, o lo programa con scheduled_at hasta 90 días antes; reply_to_comment responde en público, o en privado por mensaje directo con private en true; get_social_insights pasa los nombres de métricas directamente a Meta; y set_social_webhook_destination reenvía comentarios, menciones y mensajes directos a tu endpoint, firmados con X-EC-Signature.

MCP tool calls for the same jobs
[
  {
    "name": "publish_instagram_post",
    "arguments": {
      "account_id": "<from list_social_accounts>",
      "type": "REELS",
      "video_url": "https://cdn.example.com/launch.mp4",
      "caption": "Launch day.",
      "scheduled_at": "2026-11-06T09:00:00-03:00"
    }
  },
  {
    "name": "list_social_comments",
    "arguments": { "account_id": "<ACCOUNT_ID>", "post_id": "<IG_MEDIA_ID>" }
  },
  {
    "name": "reply_to_comment",
    "arguments": { "account_id": "<ACCOUNT_ID>", "comment_id": "<IG_COMMENT_ID>", "text": "Prices are in our bio link." }
  },
  {
    "name": "get_social_insights",
    "arguments": {
      "account_id": "<ACCOUNT_ID>",
      "metrics": ["reach", "views", "accounts_engaged"],
      "period": "day",
      "params": { "metric_type": "total_value" }
    }
  },
  {
    "name": "set_social_webhook_destination",
    "arguments": { "account_id": "<ACCOUNT_ID>", "url": "https://hooks.example.com/instagram" }
  }
]

Errores comunes

  • Calcular el hash del JSON ya analizado. Meta firma los bytes sin procesar, así que el parser de cuerpo JSON de un framework rompe la verificación de X-Hub-Signature-256; conserva el cuerpo sin procesar y analízalo después.
  • Volver a llamar a media_publish tras un timeout sin comprobar antes. Si el status_code del contenedor indica PUBLISHED, la publicación ya está en línea.
  • Leer el código 4 como limitación sin mirar el subcódigo. Con 2207051 significa que Instagram sospecha de spam, y un reintento repite la acción que acaba de restringir.
  • Enviar el app secret o el token desde código de navegador o móvil. Meta indica que las peticiones con el app secret deben estar solo en código de servidor.
Hacerlo con EasyCoexistence

De US$ 9 a US$ 0.75 por conexión al mes, con un precio que baja a medida que añades conexiones, y los primeros 3 días gratis.

Preguntas frecuentes

¿Necesito un SDK para llamar a la API de Instagram?

No. Cada llamada es una petición HTTPS con un token de acceso, así que requests en Python o fetch en Node.js bastan, como muestran los ejemplos de esta página.

¿Por qué falla media_publish justo después de crear un contenedor de Reel?

El video aún se está procesando: error 9007 con subcódigo 2207027. Revisa el status_code del contenedor una vez por minuto y publica cuando indique FINISHED.

¿Qué versión de la API debe usar el código?

Una que Meta siga sirviendo: v26.0 es la más reciente, y cada versión dura al menos dos años. Una llamada a una versión retirada se ejecuta en la versión anterior más reciente que siga disponible.

¿Cuánto cuesta easyCoexistence para acceder a la API de una cuenta de Instagram?

Cada cuenta de Instagram es una conexión: de US$ 9 a US$ 0.75 por conexión al mes, con un precio que baja a medida que añades conexiones, y los primeros 3 días gratis.

Sigue leyendo

Conecta tu primer canal en dos minutos.

Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.

  • 3 días gratis
  • Cancela cuando quieras
  • Solo APIs oficiales
  • Monitorizado 24/7

Verificado el