InloggenGratis proefperiode starten
easyCoexistence Officiële API's

Instagram API in Python en Node.js: werkende voorbeelden

De Instagram API heeft niets meer nodig dan HTTPS, dus de requests van Python en de ingebouwde fetch van Node.js volstaan: POST /<IG_ID>/media en daarna media_publish publiceert, /<IG_MEDIA_ID>/comments en /<IG_COMMENT_ID>/replies lezen reacties en beantwoorden ze, /insights geeft statistieken terug, en een webhook wordt gecontroleerd met een HMAC-SHA256 van de ruwe body. Elke fout heeft een code en subcode die bepalen of een nieuwe poging kan helpen.

easyCoexistence draait dezelfde taken als MCP-tools voor Claude, ChatGPT of je eigen agent, met het token aan zijn kant: publish_instagram_post, reply_to_comment, get_social_insights en set_social_webhook_destination, op de officiële API van Meta.

v26.0

De nieuwste Graph API-versie, geïntroduceerd op 29 juli 2026; v25.0 blijft beschikbaar tot 29 juli 2028.

Once a minute

Hoe vaak Meta voorstelt de status_code van een videocontainer te controleren, gedurende maximaal 5 minuten.

50

Het maximum aantal reacties dat één GET /<IG_MEDIA_ID>/comments-verzoek teruggeeft; antwoorden komen alleen terug via field expansion.

2207008

Een tijdelijke publicatiefout, waarbij Meta zegt 1 tot 2 keer opnieuw te proberen binnen 30 seconden tot 2 minuten.

sha256=

Het voorvoegsel in X-Hub-Signature-256, vóór de HMAC-SHA256 van de payload, versleuteld met het app secret.

Wat hebben de voorbeelden nodig?

Een runtime, een token en vier waarden. De voorbeelden roepen de Instagram API aan met Instagram Login op graph.instagram.com; een Unified Login-app gebruikt dezelfde paden met het ID van het account, op de Graph-host van Facebook Login met zijn Business Integration System User-token. Python heeft het requests-pakket nodig, plus Flask voor de webhook, en Node.js heeft versie 18 of nieuwer nodig voor zijn ingebouwde fetch.

  • GRAPH: https://graph.instagram.com/v26.0, de host en de API-versie.
  • IG_ID: het ID van het professionele account, de user_id die GET /me teruggeeft.
  • TOKEN: een langlevend Instagram User-toegangstoken, op de server bewaard.
  • APP_SECRET en VERIFY_TOKEN: voor het controleren van webhookverzoeken.

Hoe roep je de API aan en behandel je fouten in Python?

Via één helper, die de Python-voorbeelden hieronder delen. Die stuurt het token mee als access_token, werpt een MetaError op met de code, subcode en fbtrace_id van Meta, en probeert opnieuw alleen wat Meta tijdelijk noemt: codes 1 en 2, de throttlingcodes 4, 17 en 80002, en de subcodes 2207001, 2207003, 2207008 en 2207032. Code 4 met subcode 2207051 betekent vermoedelijke spam, dus die stopt meteen.

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))

Hoe roep je de API aan en behandel je fouten in Node.js?

Met dezelfde helper voor Node.js 18 of nieuwer, met fetch en zonder afhankelijkheden. Een gethrottelde aanroep wacht op estimated_time_to_regain_access, de minuten die Meta meldt in de X-Business-Use-Case-Usage-header, of 60 seconden zonder die header, omdat Meta aanroepen telt die tijdens throttling worden gedaan. needsNewToken markeert de codes 190 en 102, die geen nieuwe poging kan verhelpen.

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");
}

Hoe publiceer je een foto en een Reel in Python?

Beide volgen de containerstroom. Een fotocontainer is meteen klaar, dus media_publish komt er direct na. De video van een Reel wordt eerst verwerkt: de functie controleert de status_code eens per minuut, gedurende maximaal 5 minuten, zoals Meta voorstelt, publiceert bij FINISHED en stopt bij ERROR of EXPIRED. Afbeeldingen moeten JPEG zijn, en de media moet op een openbare URL staan.

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")

Hoe publiceer je een foto en een Reel in Node.js?

Dezelfde twee functies, die elk het nieuwe media-ID teruggeven. Een container die na vijf controles nog IN_PROGRESS is, blijft geldig tot 24 uur na zijn aanmaak, dus de fout zegt die later opnieuw te controleren. Zo voorkom je dat je een tweede container aanmaakt en het limiet van 400 per dag van het account opmaakt.

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`);
}

Hoe lees je reacties en reageer je in Python?

GET /<IG_MEDIA_ID>/comments geeft reacties op het hoogste niveau terug, nieuwste eerst, tot 50 per verzoek, en POST /<IG_COMMENT_ID>/replies plaatst een openbaar antwoord op één ervan. De functie vraagt een callback van jou om de tekst van elk antwoord en slaat reacties over waarvoor die niets teruggeeft. Verborgen reacties kunnen niet beantwoord worden, en een antwoord op een antwoord komt bij de reactie op het hoogste niveau terecht.

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)

Hoe lees je reacties en reageer je in Node.js?

Dezelfde lus in Node.js. Beide aanroepen gebruiken instagram_business_basic en instagram_business_manage_comments, en het username-veld heeft de tweede nodig. Om privé te antwoorden, stuurt POST /<IG_ID>/messages met recipient.comment_id de reageerder één DM, binnen 7 dagen na de reactie, en een vervolgbericht wacht tot die reageert.

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));

Hoe lees je inzichten in Python?

Inzichten van het account vereisen period=day met metric_type=total_value, en elke metriek meldt dan total_value.value; de inzichten van een post geven values[0].value. Het voorbeeld vraagt reach, views en accounts_engaged op het account, en reach, views, likes, comments, saved en shares op een post of Reel, wat de referentie van Meta voor beide noemt. Een metriek zonder gegevens wordt weggelaten in plaats van als 0 teruggegeven.

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}

Hoe lees je inzichten in Node.js?

Dezelfde twee verzoeken in Node.js, die elk een object teruggeven met de metriekennaam als sleutel. Geen van beide stuurt een uitsplitsing mee: Meta waarschuwt dat om een uitsplitsing vragen die een metriek niet ondersteunt, het verzoek laat mislukken met een onbekende fout, en dat inzichtgegevens tot 48 uur achterlopen, dus lees recente posts later opnieuw.

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]));
}

Hoe verifieer je een webhook in Python?

Met Flask, in twee routes op één pad. De GET beantwoordt het verificatieverzoek van Meta: wanneer hub.mode subscribe is en hub.verify_token overeenkomt, geeft hij hub.challenge terug als platte tekst, en anders een 403. De POST berekent sha256= plus de HMAC-SHA256 van de ruwe body met het app secret, vergelijkt die met X-Hub-Signature-256 in constante tijd, en antwoordt 200 voordat het trage werk begint.

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

Hoe verifieer je een webhook in Node.js?

Met de ingebouwde http-module en zonder framework. De body wordt eerst als ruwe bytes verzameld voordat iets hem parseert, omdat een geparseerde en opnieuw geserialiseerde body niet meer overeenkomt met de handtekening die Meta berekende. Meta probeert een mislukte melding tot 36 uur opnieuw, dus een handler moet ook gebeurtenissen overslaan die hij al verwerkte.

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);

Welke Meta-fouten moet de code opnieuw proberen?

Alleen de tijdelijke, want de rest geeft hetzelfde antwoord totdat er iets verandert: het bestand, de URL, een recht of de staat van het account. De foutreferenties van Meta geven de actie voor elke code die de helpers hierboven onderscheiden:

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

Hoe draai je dezelfde code op de inloggegevens van easyCoexistence?

Je kunt het niet draaien op het token van easyCoexistence: Instagram-tokens worden nooit uitgegeven (voorwaarden van Meta), dus get_social_credentials en GET /api/v1/channels/:id?credentials=1 van de Partner API geven het ID en de API-basis van het account terug, zonder token. Dezelfde taken draaien in plaats daarvan als MCP-tools, via Claude, ChatGPT of een andere MCP-client, en de helpers hierboven draaien ongewijzigd op een token van je eigen Meta-app.

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. ..."
}

Hoe doe je dezelfde taken via de MCP-connector?

Door de assistent erom te vragen, of door de tools zelf aan te roepen. publish_instagram_post maakt de container aan en publiceert die, en wacht terwijl een video wordt verwerkt, of plant hem in met scheduled_at tot 90 dagen vooruit; reply_to_comment antwoordt openbaar, of privé via DM met private op true; get_social_insights geeft metriekennamen rechtstreeks door aan Meta; en set_social_webhook_destination stuurt reacties, vermeldingen en DM's door naar jouw endpoint, ondertekend met 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" }
  }
]

Veelgemaakte fouten

  • De geparseerde JSON hashen. Meta ondertekent de ruwe bytes, dus de JSON-body-parser van een framework breekt de X-Hub-Signature-256-controle; bewaar de ruwe body en parseer hem daarna.
  • media_publish opnieuw aanroepen na een time-out zonder te kijken. Als de status_code van de container PUBLISHED aangeeft, staat de post al live.
  • Code 4 als throttling lezen zonder de subcode. Met 2207051 betekent het dat Instagram spam vermoedt, en een nieuwe poging herhaalt de actie die net werd beperkt.
  • Het app secret of het token verzenden vanuit browser- of mobiele code. Meta zegt dat verzoeken met het app secret alleen thuishoren in code aan de serverkant.
Dit doen met EasyCoexistence

US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met de eerste 3 dagen gratis.

Veelgestelde vragen

Heb ik een SDK nodig om de Instagram API aan te roepen?

Nee. Elke aanroep is een HTTPS-verzoek met een toegangstoken, dus requests in Python of fetch in Node.js volstaat, zoals de voorbeelden op deze pagina laten zien.

Waarom faalt media_publish meteen nadat een Reel-container is aangemaakt?

De video wordt nog verwerkt: fout 9007 met subcode 2207027. Controleer de status_code van de container eens per minuut en publiceer zodra hij FINISHED aangeeft.

Welke API-versie moet de code gebruiken?

Een versie die Meta nog ondersteunt: v26.0 is de nieuwste, en elke versie blijft minstens twee jaar bestaan. Een aanroep naar een verwijderde versie draait op de eerstvolgende oudere versie die nog beschikbaar is.

Hoeveel kost easyCoexistence voor API-toegang tot een Instagram-account?

Elk Instagram-account is één verbinding: US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met de eerste 3 dagen gratis.

Lees verder

Koppel je eerste kanaal in twee minuten.

Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.

  • 3 dagen gratis
  • Op elk moment opzegbaar
  • Alleen officiële API's
  • 24/7 bewaakt

Geverifieerd op