Was Instagrams content_publishing_limit-Endpunkt zurückgibt

Was liefert der Endpunkt content_publishing_limit?

Metas Endpunkt content_publishing_limit liefert eine Zählung, wie viele Container ein professionelles Instagram-Konto in einem rollierenden 24-Stunden-Fenster bereits veröffentlicht hat, zusammen mit der Obergrenze, gegen die diese Zählung gemessen wird. Es ist ein Nur-Lese-Endpunkt. Die Referenz sagt es zweimal: „Creating: This operation is not supported“ und dieselbe Zeile für Aktualisieren und Löschen.

Die Anfrageform, aus Metas Referenz übernommen:

GET https://graph.facebook.com/<API_VERSION>/<IG_USER_ID>/content_publishing_limit
  ?fields=<LIST_OF_FIELDS>
  &since=<UNIX_TIMESTAMP>
  &access_token=<ACCESS_TOKEN>

Apps auf Basis der Instagram API mit Instagram Login senden denselben Aufruf stattdessen an graph.instagram.com. Die Antwort ist ein data-Array mit einem Objekt darin:

{
  "data": [
    {
      "quota_usage": 2,
      "config": {
        "quota_total": 50,
        "quota_duration": 86400
      }
    }
  ]
}

Was bedeuten quota_usage, quota_total und quota_duration?

Drei Feldnamen tragen die ganze Antwort, und Meta definiert jeden in einem Satz.

quota_usage ist das Feld, das du umsonst bekommst. Metas Hinweis zum Parameter fields lautet: „A comma-separated list of fields you want returned. If omitted, the quota_usage field will be returned by default.“ Frag config ausdrücklich ab, sonst siehst du die Obergrenze nicht, nur die Zählung.

Der Parameter since verengt das Fenster. Meta beschreibt ihn als „A Unix timestamp no older than 24 hours“ und ergänzt: „If the since parameter is omitted, this value will be the number of times the app user has published a container within the last 24 hours.“ Du kannst nicht weiter als einen Tag zurückblicken, was dasselbe ist wie zu sagen, der Endpunkt hat kein Gedächtnis jenseits der Quote, die er durchsetzt.

Eine Merkwürdigkeit steckt in Metas eigener Beispielanfrage. Sie fragt fields=quota_usage,rate_limit_settings ab, und rate_limit_settings taucht weder in der Feldtabelle dieser Seite noch sonst irgendwo in der Instagram-Plattform-Referenz auf. Das Beispiel fragt ein Feld ab, das die Dokumentation nie definiert.

Liegt die Grenze bei 50 Beiträgen oder bei 100?

Meta veröffentlicht beide Zahlen auf aktiven Seiten und bringt sie nie zusammen. Der Leitfaden zur Inhaltsveröffentlichung sagt: „Instagram accounts are limited to 100 API-published posts within a 24-hour moving period.“ Die Referenz zu content_publishing_limit sagt, quota_total sei „currently 50“. Der Karussell-Abschnitt desselben Leitfadens sagt: „Accounts are limited to 50 published posts within a 24-hour period.“

Der Leitfaden widerspricht sich also intern, und die Referenz stellt sich auf die Seite der niedrigeren Zahl. Das ist keine vergessene, veraltete Seite, es ist die Endpunkt-Dokumentation genau des Feldes, das die Obergrenze meldet. Die Kluft zwischen dem Satz mit 100 Beiträgen und dem Satz mit 50 Beiträgen ist alt genug, um mehrere Graph-API-Versionen überlebt zu haben.

Die praktische Auflösung ist, keine der beiden Zahlen zu lesen und stattdessen quota_total aus der Antwort zu lesen. Das ist die Zahl, gegen die das Konto tatsächlich gemessen wird, sie kommt pro Konto, und sie kostet eine Anfrage.

Was zählt gegen die Quote und was nicht?

Veröffentlichen zählt. Erstellen nicht. Die Unterscheidung ist in Metas Wortlaut exakt, denn quota_usage zählt „the number of times the app user has published an IG Container“, und der Leitfaden benennt den Endpunkt, an dem durchgesetzt wird: „This limit is enforced on the POST /<IG_ID>/media_publish endpoint when attempting to publish a media container.“

Die Container-Erstellung hat eine eigene Obergrenze, die die meisten Teams nie erreichen. Die Referenz zum media-Endpunkt hält fest: „An Instagram account can only create 400 containers within a rolling 24 hour period.“ Acht Container pro Veröffentlichung ist ein großzügiges Verhältnis, ein Ablauf, der die Container-Erstellung aggressiv wiederholt, kann dieses Budget also aufbrauchen, während quota_usage noch null anzeigt, und der Fehlschlag wird überhaupt nicht wie ein Veröffentlichungslimit aussehen.

Karussells sind der Fall, den du verinnerlichen solltest, wenn du Bildsätze bündelst. Zehn Bilder werden zu einer Quoteneinheit, was das Planen von Karussellbeiträgen über Instagram und Facebook gegenüber der Obergrenze weit billiger macht als zehn Einzelbeiträge mit denselben Bildern.

Wie solltest du die Antwort vor dem Veröffentlichen lesen?

Ruf content_publishing_limit vor der Veröffentlichung auf, nicht nach dem Fehlschlag, und vergleiche quota_usage mit config.quota_total statt mit einer fest verdrahteten Zahl. Meta bittet direkt darum: „We recommend that your app also enforce the publishing rate limit, especially if your app allows app users to schedule posts to be published in the future.“

Drei Details entscheiden, ob diese Prüfung etwas taugt:

• Frag config ausdrücklich ab. Ohne es bekommst du eine Nutzungszahl und nichts zum Vergleichen.
• Behandle das Fenster als rollierend, nicht als täglich. quota_duration sind 86.400 Sekunden rückwärts von jetzt gemessen, Kapazität kommt also über den Tag hinweg schrittweise zurück und nicht zu einer Reset-Stunde.
• Lies vor jeder Veröffentlichung in einem Stapel neu, nicht einmal pro Stapel. Eine Warteschlange mit 20 Beiträgen, die die Quote einmal zu Beginn geprüft hat, ist eine Warteschlange, die bei Beitrag 14 über die Obergrenze laufen kann.

Bei Planungstools beißt das am härtesten, weil eine Warteschlange sich Stunden oder Tage im Voraus auf Veröffentlichungszeiten festlegt, während die Quote in der Gegenwart verbraucht wird. Das ist dieselbe Problemklasse wie bei jeder Social-Media-Planungs-API, die auf einer Plattformquote gebaut ist: Der Plan wird gegen Kapazität geschrieben, die noch nicht gemessen wurde.

Welchen Fehler liefert Instagram, wenn du die Grenze erreichst?

Metas Referenz zu Fehlercodes führt ihn präzise auf. Ein Konto, das seine Veröffentlichungsquote ausgeschöpft hat, bekommt HTTP 400, Code 9, Subcode 2207042, mit der Nutzermeldung: „You reached maximum number of posts that is allowed to be published by Content Publishing API.“

Die empfohlene Lösung lautet: „The app user has reached their daily publishing limit. Advise the app's user to try again the following day.“ Beachte die Unstimmigkeit. Das Fenster ist überall sonst als rollierender 24-Stunden-Zeitraum dokumentiert, und der Rat hier sagt „the following day“, was Kalendersprache für ein rollierendes Fenster ist. Kapazität wird 24 Stunden nach jeder einzelnen Veröffentlichung frei, nicht um Mitternacht.

Benachbarte Fehlschläge sehen anders aus und gehören getrennt behandelt. Code 4, Subcode 2207051 liefert „We restrict certain activity to protect our community. Tell us if you think we made a mistake“, was Meta auf Veröffentlichungen zurückführt, die „suspected to be spam“ sind. Das ist kein Quotenproblem, und es morgen erneut zu versuchen löst es nicht. Andere Plattformen ziehen dieselbe Linie zwischen einer Quote, die man aussitzen kann, und einer Einschränkung, die man nicht aussitzen kann, weshalb Pinterests veröffentlichte Rate Limits und Instagrams in derselben Warteschlange getrennte Behandlungspfade brauchen.

Welche Berechtigungen braucht der Aufruf?

Die Token-Scopes unterscheiden sich nach Login-Verfahren, und Meta führt beide auf. Die Instagram API mit Instagram Login braucht instagram_business_basic und instagram_business_content_publish. Die Instagram API mit Facebook Login braucht instagram_basic, instagram_content_publish und pages_read_engagement, plus ads_management oder ads_read, wenn „the app user was granted a role via the Business Manager on the Page connected to the targeted IG User“.

Das sind dieselben Scopes, die der Veröffentlichungsaufruf selbst verlangt, ein Token, das veröffentlichen kann, kann also auch die Quote lesen. Es gibt keinen billigeren Nur-Lese-Scope zum Prüfen der Kapazität, was heißt, dass die Quotenprüfung jeder App offensteht, die sie je brauchen würde.

Häufig gestellte Fragen

Wie lautet der vollständige Pfad des Endpunkts?

GET /<IG_USER_ID>/content_publishing_limit, auf graph.facebook.com für die Instagram API mit Facebook Login und auf graph.instagram.com für die Instagram API mit Instagram Login.

Liefert der Endpunkt die Grenze standardmäßig?

Nein. Standardmäßig kommt nur quota_usage zurück. Metas Referenz sagt, das config-Objekt, das quota_total und quota_duration hält, muss über den Parameter fields angefragt werden.

Wie weit zurück reicht der Parameter since?

24 Stunden. Meta beschreibt den Wert als „A Unix timestamp no older than 24 hours“, der Endpunkt kann Nutzung aus einem früheren Fenster also nicht melden.

Zählen fehlgeschlagene Veröffentlichungsversuche gegen quota_usage?

Meta sagt es nicht. Das Feld zählt, wie oft der Nutzer „has published an IG Container“, was nach erfolgreichen Veröffentlichungen klingt, doch die Dokumentation behandelt nie eine Veröffentlichung, die nach der Annahme fehlschlägt.

Verbraucht das Erstellen eines Media-Containers Quote?

Nein. Die Container-Erstellung unterliegt einer separaten Regel, dass ein Konto „can only create 400 containers within a rolling 24 hour period“, und Container verfallen nach 24 Stunden, ob sie veröffentlicht werden oder nicht.

Warum sagt quota_total 50, wenn der Leitfaden 100 sagt?

Meta veröffentlicht beide Zahlen und löst sie nie auf. Die Referenz zum Endpunkt sagt, quota_total sei „currently 50“, der Leitfaden zur Inhaltsveröffentlichung sagt in seinem Abschnitt zu Rate Limits 100 und im Karussell-Abschnitt wieder 50. Lies den Wert aus der Antwort, statt einer der Seiten zu vertrauen.

Wie oft solltest du die Quote in einer Veröffentlichungswarteschlange erneut prüfen?

Prüfe vor jeder einzelnen Veröffentlichung in der Warteschlange neu, nicht nur einmal am Anfang. Das Zeitfenster läuft fortlaufend, sodass eine Charge von 20 Beiträgen, die die Kapazität nur zu Beginn geprüft hat, bis Beitrag 14 über die Grenze hinauslaufen kann. Der Vergleich von quota_usage mit config.quota_total bei jedem Sendevorgang erkennt diese Abweichung, bevor Instagram es tut.

Zählt ein Karussell als ein Beitrag oder als mehrere gegen quota_usage?

Ein Karussell zählt als ein Beitrag, unabhängig davon, wie viele Bilder es enthält, laut Metas Satz "Carousels count as a single post". Zehn gemeinsam veröffentlichte Bilder verbrauchen dieselbe einzelne Einheit von quota_usage wie ein einzelnes Bild. Das macht Karussells gegen die Grenze deutlich günstiger als dieselben Bilder einzeln zu veröffentlichen.

Was passiert, wenn eine App das Veröffentlichungslimit ignoriert?

Meta empfiehlt, dass Apps das Ratenlimit selbst durchsetzen, besonders wenn sie Nutzern erlauben, Beiträge im Voraus zu planen, weil das Auslassen der Prüfung den Fehler nur bis zum Veröffentlichungszeitpunkt verschiebt. Ein Konto über der Quote erhält HTTP 400, Code 9, Subcode 2207042, und die Kapazität kehrt 24 Stunden nach jeder Veröffentlichung zurück, nicht bei einem täglichen Zurücksetzen. Ein Planungstool, das die Vorabprüfung auslässt, erfährt das erst, nachdem es sich bereits auf einen Veröffentlichungszeitpunkt festgelegt hat, den es nicht mehr einhalten kann.

Ist eine Spam-Beschränkung dasselbe wie das Erreichen der Veröffentlichungsquote?

Eine Spam-Beschränkung ist ein anderer Fehler als ein Quotenlimit. Code 4, Subcode 2207051, tritt auf, wenn eine Veröffentlichung "suspected to be spam" ist, und ein erneuter Versuch am nächsten Tag löst das Problem nicht so, wie das Abwarten der Quote es tun würde. Dieser Unterschied zählt für eine Warteschlange, weil beide Fehler getrennte Behandlungspfade brauchen, einen, der wartet, und einen, der stoppt und die Inhalte kennzeichnet.