Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

API Instagram en Python et Node.js : exemples concrets

L'API Instagram n'exige rien d'autre que HTTPS : requests en Python et fetch intégré à Node.js suffisent. POST /<IG_ID>/media puis media_publish publient, /<IG_MEDIA_ID>/comments et /<IG_COMMENT_ID>/replies lisent et répondent aux commentaires, /insights renvoie les métriques, et un webhook se vérifie par un HMAC-SHA256 du corps brut. Chaque erreur porte un code et un subcode qui indiquent si une nouvelle tentative peut aider.

easyCoexistence exécute les mêmes tâches sous forme d'outils MCP pour Claude, ChatGPT ou votre propre agent, avec le token conservé de son côté : publish_instagram_post, reply_to_comment, get_social_insights et set_social_webhook_destination, sur l'API officielle de Meta.

v26.0

La dernière version de l'API Graph, publiée le 29 juillet 2026 ; la v25.0 reste disponible jusqu'au 29 juillet 2028.

Once a minute

La fréquence à laquelle Meta suggère de vérifier le status_code d'un conteneur vidéo, pendant 5 minutes au plus.

50

Le nombre maximal de commentaires qu'une requête GET /<IG_MEDIA_ID>/comments renvoie ; les réponses n'arrivent que par expansion de champ.

2207008

Une erreur de publication temporaire, pour laquelle Meta conseille de réessayer 1 à 2 fois dans un délai de 30 secondes à 2 minutes.

sha256=

Le préfixe de X-Hub-Signature-256, placé avant le HMAC-SHA256 du payload signé avec le secret de l'application.

De quoi les exemples ont-ils besoin ?

Un runtime, un token et quatre valeurs. Les exemples appellent l'API Instagram avec Instagram Login sur graph.instagram.com ; une application Unified Login utilise les mêmes chemins avec l'ID du compte, sur l'hôte Graph de Facebook Login et avec son token Business Integration System User. Python nécessite le package requests, plus Flask pour le webhook, et Node.js la version 18 ou ultérieure pour son fetch intégré.

  • GRAPH : https://graph.instagram.com/v26.0, l'hôte et la version de l'API.
  • IG_ID : l'identifiant du compte professionnel, le user_id renvoyé par GET /me.
  • TOKEN : un token d'accès utilisateur Instagram de longue durée, conservé côté serveur.
  • APP_SECRET et VERIFY_TOKEN : pour vérifier les requêtes du webhook.

Comment appeler l'API et gérer les erreurs en Python ?

Par une seule fonction utilitaire, partagée par les exemples Python ci-dessous. Elle envoie le token sous access_token, lève MetaError avec le code, le subcode et le fbtrace_id de Meta, et ne réessaie que ce que Meta qualifie de temporaire : les codes 1 et 2, les codes de limitation de débit 4, 17 et 80002, et les subcodes 2207001, 2207003, 2207008 et 2207032. Le code 4 avec le subcode 2207051 signale un spam suspecté : la fonction s'arrête immédiatement.

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

Comment appeler l'API et gérer les erreurs en Node.js ?

Avec la même fonction pour Node.js 18 ou ultérieur, qui utilise fetch sans aucune dépendance. Un appel limité attend estimated_time_to_regain_access, les minutes indiquées par Meta dans l'en-tête X-Business-Use-Case-Usage, ou 60 secondes à défaut, car Meta comptabilise les appels faits pendant la limitation. needsNewToken signale les codes 190 et 102, qu'aucune nouvelle tentative ne peut corriger.

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

Comment publier une photo et un Reel en Python ?

Les deux suivent le flux de conteneur. Un conteneur photo est prêt immédiatement, donc media_publish vient juste après. La vidéo d'un Reel est d'abord traitée : la fonction vérifie le status_code une fois par minute, pendant 5 minutes au plus, comme le suggère Meta, publie lorsque la valeur est FINISHED et s'arrête sur ERROR ou EXPIRED. Les images doivent être au format JPEG, et le média doit se trouver à une URL publique.

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

Comment publier une photo et un Reel en Node.js ?

Les mêmes deux fonctions, chacune renvoyant l'ID du nouveau média. Un conteneur encore IN_PROGRESS après cinq vérifications reste valide jusqu'à 24 heures après sa création ; le message d'erreur invite donc à le vérifier plus tard, ce qui évite de créer un second conteneur sur les 400 autorisés par jour pour le compte.

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

Comment lire les commentaires et répondre en Python ?

GET /<IG_MEDIA_ID>/comments renvoie les commentaires de premier niveau, du plus récent au plus ancien, jusqu'à 50 par requête, et POST /<IG_COMMENT_ID>/replies publie une réponse publique à l'un d'eux. La fonction demande à l'une de vos fonctions de rappel le texte de chaque réponse et passe les commentaires pour lesquels elle ne renvoie rien. Les commentaires masqués ne peuvent pas recevoir de réponse, et une réponse à une réponse s'affiche sous le commentaire de premier niveau.

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)

Comment lire les commentaires et répondre en Node.js ?

La même boucle en Node.js. Les deux appels utilisent instagram_business_basic et instagram_business_manage_comments, et le champ username exige le second. Pour répondre en privé à la place, POST /<IG_ID>/messages avec recipient.comment_id envoie au commentateur un seul message direct, dans les 7 jours suivant le commentaire, et toute relance attend qu'il réponde.

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

Comment lire les insights en Python ?

Les insights du compte prennent period=day avec metric_type=total_value, et chaque métrique renvoie alors total_value.value ; les insights d'une publication renvoient values[0].value. L'exemple demande reach, views et accounts_engaged sur le compte, puis reach, views, likes, comments, saved et shares sur une publication ou un Reel, que la référence de Meta indique pour les deux. Une métrique sans données est omise plutôt que renvoyée à 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}

Comment lire les insights en Node.js ?

Les deux mêmes requêtes en Node.js, chacune renvoyant un objet indexé par nom de métrique. Aucune n'envoie de ventilation : Meta prévient qu'en demander une qu'une métrique ne prend pas en charge fait échouer la requête avec une erreur inconnue, et que les données d'insights peuvent accuser jusqu'à 48 heures de retard, il faut donc relire les publications récentes plus tard.

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

Comment vérifier un webhook en Python ?

Avec Flask, en deux routes sur un même chemin. Le GET répond à la requête de vérification de Meta : lorsque hub.mode vaut subscribe et que hub.verify_token correspond, il renvoie hub.challenge en texte brut, sinon un 403. Le POST calcule sha256= suivi du HMAC-SHA256 du corps brut avec le secret de l'application, le compare à X-Hub-Signature-256 en temps constant, et répond 200 avant tout traitement lent.

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

Comment vérifier un webhook en Node.js ?

Avec le module http intégré, sans framework. Le corps est collecté en octets bruts avant tout parsing, car un corps analysé puis re-sérialisé ne correspond plus à la signature calculée par Meta. Meta renouvelle l'envoi d'une notification échouée pendant 36 heures au plus ; un gestionnaire doit donc aussi ignorer les événements déjà traités.

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

Quelles erreurs de Meta le code doit-il réessayer ?

Seulement les erreurs temporaires, car les autres renvoient la même réponse tant que rien ne change : le fichier, l'URL, une autorisation ou l'état du compte. Les références d'erreurs de Meta indiquent l'action à mener pour chaque code que les fonctions ci-dessus distinguent :

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

Comment exécuter le même code avec les identifiants d'easyCoexistence ?

Vous ne pouvez pas l'exécuter avec le token d'easyCoexistence : les tokens Instagram ne sont jamais remis (conditions de Meta), donc get_social_credentials et GET /api/v1/channels/:id?credentials=1 de la Partner API renvoient l'ID du compte et la base de l'API sans token. Les mêmes tâches s'exécutent plutôt sous forme d'outils MCP, via Claude, ChatGPT ou un autre client MCP, et les fonctions ci-dessus s'exécutent sans modification avec un token de votre propre app 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. ..."
}

Comment faire les mêmes tâches avec le connecteur MCP ?

En le demandant à l'assistant, ou en appelant vous-même les outils. publish_instagram_post crée et publie le conteneur, en attendant la fin du traitement d'une vidéo, ou le planifie avec scheduled_at jusqu'à 90 jours à l'avance ; reply_to_comment répond publiquement, ou en privé par message direct avec private à true ; get_social_insights transmet les noms de métriques directement à Meta ; et set_social_webhook_destination transfère les commentaires, les mentions et les messages privés à votre endpoint, signés avec 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" }
  }
]

Erreurs courantes

  • Hacher le JSON analysé. Meta signe les octets bruts : le parseur JSON d'un framework casse la vérification de X-Hub-Signature-256 ; conservez le corps brut et analysez-le ensuite.
  • Rappeler media_publish après un délai d'attente sans vérifier. Si le status_code du conteneur indique PUBLISHED, la publication est déjà en ligne.
  • Lire le code 4 comme une limitation sans le subcode. Avec 2207051, cela signifie qu'Instagram suspecte du spam, et une nouvelle tentative répète l'action qu'il vient de restreindre.
  • Envoyer le secret de l'application ou le token depuis du code navigateur ou mobile. Meta indique que les requêtes portant le secret de l'application doivent rester dans du code côté serveur uniquement.
Faire cela avec EasyCoexistence

De US$ 9 à US$ 0.75 par connexion et par mois, dégressif à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.

Questions fréquemment posées

Ai-je besoin d'un SDK pour appeler l'API Instagram ?

Non. Chaque appel est une requête HTTPS avec un token d'accès ; requests en Python ou fetch en Node.js suffisent, comme le montrent les exemples de cette page.

Pourquoi media_publish échoue-t-il juste après la création d'un conteneur Reel ?

La vidéo est encore en cours de traitement : erreur 9007 avec le subcode 2207027. Vérifiez le status_code du conteneur une fois par minute et publiez lorsqu'il affiche FINISHED.

Quelle version de l'API le code doit-il utiliser ?

Celle que Meta sert encore : la v26.0 est la plus récente, et chaque version dure au moins deux ans. Un appel vers une version supprimée est traité par la version immédiatement antérieure encore disponible.

Combien coûte easyCoexistence pour l'accès API à un compte Instagram ?

Chaque compte Instagram correspond à une connexion : de US$ 9 à US$ 0.75 par connexion et par mois, dégressif à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le