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.
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.
Con qué frecuencia Meta sugiere revisar el status_code de un contenedor de video, durante no más de 5 minutos.
El máximo de comentarios que devuelve una petición GET /<IG_MEDIA_ID>/comments; las respuestas solo llegan mediante expansión de campos.
Un error temporal de publicación, que Meta indica reintentar 1 o 2 veces en un plazo de 30 segundos a 2 minutos.
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, eluser_idque devuelve GET /me.- TOKEN: un token de acceso de usuario de Instagram de larga duración, guardado en el servidor.
APP_SECRETyVERIFY_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.
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.
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.
# 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.
// 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.
# 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.
// 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.
# 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.
// 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.
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.
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:
¿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.
{
"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.
[
{
"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.
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