Instagram API in Python und Node.js: funktionierende Beispiele
Die Instagram API braucht nichts außer HTTPS, deshalb reichen Pythons requests und das eingebaute fetch in Node.js. Mit POST /<IG_ID>/media und media_publish wird veröffentlicht, /<IG_MEDIA_ID>/comments und /<IG_COMMENT_ID>/replies lesen und beantworten Kommentare, /insights liefert Kennzahlen, und ein Webhook wird über einen HMAC-SHA256 des rohen Body geprüft. Jeder Fehler trägt einen Code und einen Subcode, die entscheiden, ob eine Wiederholung helfen kann.
easyCoexistence führt dieselben Aufgaben als MCP-Tools für Claude, ChatGPT oder Ihren eigenen Agenten aus, wobei das Token auf seiner Seite bleibt: publish_instagram_post, reply_to_comment, get_social_insights und set_social_webhook_destination, über die offizielle API von Meta.
Die neueste Graph-API-Version, eingeführt am 29. Juli 2026; v25.0 bleibt bis zum 29. Juli 2028 verfügbar.
Wie oft Meta empfiehlt, den status_code eines Video-Containers zu prüfen, höchstens 5 Minuten lang.
Die meisten Kommentare, die eine GET /<IG_MEDIA_ID>/comments-Anfrage zurückgibt; Antworten kommen nur über Feldexpansion zurück.
Ein temporärer Veröffentlichungsfehler, bei dem Meta empfiehlt, 1 bis 2 Mal innerhalb von 30 Sekunden bis 2 Minuten erneut zu versuchen.
Das Präfix in X-Hub-Signature-256, vor dem HMAC-SHA256 der Payload, der mit dem App Secret als Schlüssel gebildet wird.
Was brauchen die Beispiele?
Eine Laufzeitumgebung, ein Token und vier Werte. Die Beispiele rufen die Instagram API über Instagram Login auf graph.instagram.com auf. Eine Unified-Login-App nutzt dieselben Pfade mit der ID des Kontos, auf dem Graph-Host von Facebook Login und mit ihrem Business-Integration-System-User-Token. Python braucht das Paket requests, dazu Flask für den Webhook, und Node.js benötigt Version 18 oder neuer für das eingebaute fetch.
- GRAPH: https://graph.instagram.com/v26.0, der Host und die API-Version.
IG_ID: die ID des professionellen Kontos, dieuser_id, die GET /me zurückgibt.- TOKEN: ein langlebiges Instagram-User-Access-Token, das auf dem Server bleibt.
APP_SECRETundVERIFY_TOKEN: für die Prüfung von Webhook-Anfragen.
Wie rufe ich die API auf und behandle Fehler in Python?
Über eine Hilfsfunktion, die alle Python-Beispiele unten gemeinsam nutzen. Sie sendet das Token als access_token, wirft MetaError mit code, subcode und fbtrace_id von Meta und wiederholt nur, was Meta als temporär bezeichnet: die Codes 1 und 2, die Drosselungscodes 4, 17 und 80002 sowie die Subcodes 2207001, 2207003, 2207008 und 2207032. Code 4 mit Subcode 2207051 bedeutet einen vermuteten Spam und stoppt sofort.
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))Wie rufe ich die API auf und behandle Fehler in Node.js?
Mit derselben Hilfsfunktion für Node.js 18 oder neuer, mit fetch und ohne Abhängigkeiten. Ein gedrosselter Aufruf wartet auf estimated_time_to_regain_access, die Minuten, die Meta im Header X-Business-Use-Case-Usage angibt, oder ohne diesen Wert 60 Sekunden, weil Meta Aufrufe mitzählt, die während der Drosselung erfolgen. needsNewToken markiert die Codes 190 und 102, die keine Wiederholung beheben kann.
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");
}Wie veröffentliche ich ein Foto und ein Reel in Python?
Beide folgen dem Container-Ablauf. Ein Foto-Container ist sofort fertig, deshalb folgt media_publish direkt danach. Das Video eines Reels wird zuerst verarbeitet: Die Funktion prüft den status_code einmal pro Minute, höchstens 5 Minuten lang, wie Meta empfiehlt, veröffentlicht bei FINISHED und bricht bei ERROR oder EXPIRED ab. Bilder müssen im JPEG-Format vorliegen, und die Medien müssen unter einer öffentlichen URL erreichbar sein.
# 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")Wie veröffentliche ich ein Foto und ein Reel in Node.js?
Dieselben zwei Funktionen, die jeweils die neue Medien-ID zurückgeben. Ein Container, der nach fünf Prüfungen noch IN_PROGRESS ist, bleibt bis 24 Stunden nach seiner Erstellung gültig. Die Fehlermeldung rät deshalb, später erneut zu prüfen. Das spart einen zweiten Container, der auf das Tageslimit des Kontos von 400 angerechnet würde.
// 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`);
}Wie lese ich Kommentare und antworte in Python?
GET /<IG_MEDIA_ID>/comments liefert Kommentare der obersten Ebene, die neuesten zuerst, bis zu 50 pro Anfrage. POST /<IG_COMMENT_ID>/replies veröffentlicht eine öffentliche Antwort auf einen davon. Die Funktion fragt für jede Antwort eine Rückruffunktion Ihres Codes nach dem Text ab und überspringt Kommentare, für die sie keinen Text erhält. Verborgene Kommentare können nicht beantwortet werden, und eine Antwort auf eine Antwort landet beim Kommentar der obersten Ebene.
# 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)Wie lese ich Kommentare und antworte in Node.js?
Dieselbe Schleife in Node.js. Beide Aufrufe benötigen instagram_business_basic und instagram_business_manage_comments, und das Feld username braucht das zweite. Um stattdessen privat zu antworten, sendet POST /<IG_ID>/messages mit recipient.comment_id eine DM an die Person, die kommentiert hat, innerhalb von 7 Tagen nach dem Kommentar. Eine Folgenachricht wartet, bis die Person antwortet.
// 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));Wie lese ich Insights in Python?
Kontoinsights verlangen period=day mit metric_type=total_value, und jede Kennzahl liefert dann total_value.value. Die Insights eines Beitrags liefern values[0].value. Das Beispiel fragt beim Konto reach, views und accounts_engaged ab, bei einem Beitrag oder Reel reach, views, likes, comments, saved und shares, wie die Referenz von Meta für beide auflistet. Eine Kennzahl ohne Daten wird weggelassen und nicht als 0 zurückgegeben.
# 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}Wie lese ich Insights in Node.js?
Dieselben zwei Anfragen in Node.js, die jeweils ein Objekt mit dem Metriknamen als Schlüssel zurückgeben. Keine sendet eine Aufschlüsselung: Meta warnt, dass eine Anfrage nach einer Aufschlüsselung, die eine Kennzahl nicht unterstützt, mit einem unbekannten Fehler scheitert. Außerdem können Insights-Daten bis zu 48 Stunden hinterherhinken, daher sollten Sie aktuelle Beiträge später erneut abfragen.
// 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]));
}Wie prüfe ich einen Webhook in Python?
Mit Flask, in zwei Routen auf demselben Pfad. Die GET-Route beantwortet Metas Verifizierungsanfrage: Wenn hub.mode subscribe ist und hub.verify_token übereinstimmt, gibt sie hub.challenge als Klartext zurück, andernfalls 403. Die POST-Route berechnet sha256= plus den HMAC-SHA256 des rohen Body mit dem App Secret, vergleicht ihn mit X-Hub-Signature-256 in konstanter Zeit und antwortet mit 200, bevor langsame Arbeit beginnt.
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 "", 200Wie prüfe ich einen Webhook in Node.js?
Mit dem eingebauten Modul http und ohne Framework. Der Body wird als Rohbytes gesammelt, bevor ihn etwas parst, denn ein geparster und erneut serialisierter Body passt nicht mehr zur Signatur, die Meta berechnet hat. Meta wiederholt eine fehlgeschlagene Benachrichtigung bis zu 36 Stunden lang, deshalb sollte ein Handler auch Ereignisse überspringen, die er schon verarbeitet hat.
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);Welche Meta-Fehler soll der Code wiederholen?
Nur die temporären, denn die übrigen liefern dieselbe Antwort, bis sich etwas ändert: die Datei, die URL, eine Berechtigung oder der Status des Kontos. Die Fehlerreferenzen von Meta nennen für jeden Code, den die Hilfsfunktionen oben unterscheiden, die passende Maßnahme:
Wie führe ich denselben Code mit den Zugangsdaten von easyCoexistence aus?
Sie können es nicht mit dem Token von easyCoexistence ausführen: Instagram-Tokens werden nie herausgegeben (Bedingungen von Meta), daher liefern get_social_credentials und GET /api/v1/channels/:id?credentials=1 der Partner API die ID des Kontos und die API-Basis ohne Token. Dieselben Aufgaben laufen stattdessen als MCP-Tools, über Claude, ChatGPT oder einen anderen MCP-Client, und die Hilfsfunktionen oben laufen unverändert mit einem Token aus Ihrer eigenen Meta-App.
{
"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. ..."
}Wie erledige ich dieselben Aufgaben über den MCP-Connector?
Indem Sie den Assistenten darum bitten oder die Tools selbst aufrufen. publish_instagram_post erstellt und veröffentlicht den Container und wartet, während ein Video verarbeitet wird, oder plant ihn mit scheduled_at bis zu 90 Tage im Voraus. reply_to_comment antwortet öffentlich oder privat per DM, wenn private auf true gesetzt ist. get_social_insights gibt Metriknamen direkt an Meta weiter, und set_social_webhook_destination leitet Kommentare, Erwähnungen und DMs an Ihren Endpoint weiter, signiert mit 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" }
}
]Häufige Fehler
- Das geparste JSON hashen. Meta signiert die Rohbytes, daher bricht der JSON-Body-Parser eines Frameworks die Prüfung von X-Hub-Signature-256. Behalten Sie den rohen Body und parsen Sie ihn danach.
- media_publish nach einem Timeout erneut aufrufen, ohne nachzusehen. Steht der status_code des Containers auf PUBLISHED, ist der Beitrag bereits live.
- Code 4 ohne Subcode als Drosselung lesen. Mit 2207051 bedeutet er, dass Instagram Spam vermutet, und eine Wiederholung wiederholt die Aktion, die gerade eingeschränkt wurde.
- Das App Secret oder das Token aus Browser- oder Mobile-Code senden. Meta sagt, Anfragen mit dem App Secret gehören nur in serverseitigen Code.
US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit jeder weiteren Verbindung, mit den ersten 3 Tagen als kostenlose Testphase.
Häufig gestellte Fragen
Brauche ich ein SDK, um die Instagram API aufzurufen?
Nein. Jeder Aufruf ist eine HTTPS-Anfrage mit einem Access Token, daher reichen requests in Python oder fetch in Node.js, wie die Beispiele auf dieser Seite zeigen.
Warum schlägt media_publish direkt nach dem Erstellen eines Reel-Containers fehl?
Das Video wird noch verarbeitet: Fehler 9007 mit Subcode 2207027. Prüfen Sie den status_code des Containers einmal pro Minute und veröffentlichen Sie, sobald er FINISHED anzeigt.
Welche API-Version sollte der Code verwenden?
Diejenige, die Meta noch bereitstellt: v26.0 ist die neueste, und jede Version besteht mindestens zwei Jahre. Ein Aufruf einer entfernten Version läuft auf der nächstälteren Version, die noch verfügbar ist.
Was kostet easyCoexistence für den API-Zugriff auf ein Instagram-Konto?
Jedes Instagram-Konto ist eine Verbindung: US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit jeder weiteren Verbindung, mit den ersten 3 Tagen als kostenlose Testphase.
Weiterlesen
Verbinden Sie Ihren ersten Kanal in zwei Minuten.
Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.
- 3 Tage kostenlos
- Jederzeit kündbar
- Nur offizielle APIs
- Überwacht rund um die Uhr (24/7)
Verifiziert am