O que o endpoint content_publishing_limit do Instagram devolve

O que o endpoint content_publishing_limit devolve?

O endpoint content_publishing_limit da Meta devolve a contagem de quantos containers uma conta profissional do Instagram já publicou dentro de uma janela móvel de 24 horas, junto com o teto contra o qual essa contagem é medida. É um endpoint somente de leitura. A referência diz isso duas vezes: "Creating: This operation is not supported" e a mesma linha para atualizar e apagar.

O formato da requisição, copiado da referência da Meta:

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 construídos sobre a Instagram API com Instagram Login mandam a mesma chamada para graph.instagram.com. A resposta é um array data com um objeto dentro:

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

O que significam quota_usage, quota_total e quota_duration?

Três nomes de campo carregam a resposta inteira, e a Meta define cada um em uma frase.

quota_usage é o campo que você recebe de graça. A nota da Meta sobre o parâmetro fields diz: "A comma-separated list of fields you want returned. If omitted, the quota_usage field will be returned by default." Peça config explicitamente ou você não vê o teto, só a contagem.

O parâmetro since estreita a janela. A Meta o descreve como "A Unix timestamp no older than 24 hours", e acrescenta que "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." Você não consegue olhar mais para trás do que um dia, o que é a mesma coisa que dizer que o endpoint não tem memória além da cota que aplica.

Uma esquisitice está na própria requisição de exemplo da Meta. Ela consulta fields=quota_usage,rate_limit_settings, e rate_limit_settings não aparece na tabela de campos daquela página nem em nenhum outro lugar da referência da Instagram Platform. O exemplo pede um campo que a documentação nunca define.

O teto é 50 posts ou 100?

A Meta publica os dois números em páginas ativas, e nunca os concilia. O guia de publicação de conteúdo afirma: "Instagram accounts are limited to 100 API-published posts within a 24-hour moving period." A referência de content_publishing_limit afirma que quota_total é "currently 50." A seção de carrossel desse mesmo guia afirma: "Accounts are limited to 50 published posts within a 24-hour period."

Ou seja, o guia se contradiz internamente, e a referência fica do lado do número menor. Essa não é uma página esquecida pela Meta, é a documentação do endpoint do exato campo que reporta o teto. A distância entre a frase dos 100 posts e a frase dos 50 posts é velha o bastante para ter sobrevivido a várias versões da Graph API.

A resolução prática é parar de ler qualquer um dos números e ler quota_total da resposta. Esse é o número contra o qual a conta está de fato sendo medida, ele chega por conta, e custa uma requisição para obter.

O que conta contra a cota e o que não conta?

Publicar conta. Criar não. A distinção é exata na redação da Meta, porque quota_usage conta "the number of times the app user has published an IG Container", e o guia nomeia o endpoint onde a regra é aplicada: "This limit is enforced on the POST /<IG_ID>/media_publish endpoint when attempting to publish a media container."

A criação de containers tem um teto próprio que quase nenhum time alcança. A referência do endpoint de mídia afirma: "An Instagram account can only create 400 containers within a rolling 24 hour period." Oito containers por publicação é uma proporção generosa, então um fluxo que repete a criação de containers com agressividade consegue esgotar esse orçamento enquanto quota_usage ainda marca zero, e a falha não vai se parecer em nada com um limite de taxa de publicação.

Carrosséis são o caso que vale internalizar se você agrupa conjuntos de imagens. Dez imagens viram uma unidade de cota, o que torna agendar posts em carrossel no Instagram e no Facebook muito mais barato contra o teto do que dez posts únicos carregando as mesmas imagens.

Como ler a resposta antes de publicar?

Chame o content_publishing_limit antes da publicação, não depois da falha, e compare quota_usage com config.quota_total em vez de com um número que você fixou no código. A Meta pede isso diretamente: "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."

Três detalhes decidem se essa checagem vale alguma coisa:

• Peça config explicitamente. Sem ele você recebe uma contagem de uso e nada com que compará-la.
• Trate a janela como móvel, não diária. quota_duration é 86400 segundos medidos para trás a partir de agora, então a capacidade volta aos poucos ao longo do dia em vez de em uma hora de virada.
• Releia antes de cada publicação de um lote, não uma vez por lote. Uma fila de 20 posts que checou a cota uma vez no começo é uma fila que consegue passar do teto no post 14.

Ferramentas de agendamento são onde isso morde mais forte, porque uma fila se compromete com horários de publicação com horas ou dias de antecedência enquanto a cota é gasta no presente. É a mesma classe de problema de qualquer API de agendamento de redes sociais construída sobre uma cota de plataforma: o calendário é escrito contra capacidade que ainda não foi medida.

Que erro o Instagram devolve quando você bate no teto?

A referência de códigos de erro da Meta lista isso com precisão. Uma conta que esgotou a cota de publicação recebe HTTP 400, código 9, subcódigo 2207042, com a mensagem ao usuário: "You reached maximum number of posts that is allowed to be published by Content Publishing API."

A solução recomendada diz: "The app user has reached their daily publishing limit. Advise the app's user to try again the following day." Repare no descompasso. A janela é documentada como um período móvel de 24 horas em todo o resto, e o conselho aqui diz "the following day", que é linguagem de calendário para uma janela móvel. A capacidade se libera 24 horas depois de cada publicação individual, não à meia-noite.

Falhas vizinhas se parecem diferentes e devem ser tratadas separadamente. O código 4, subcódigo 2207051 devolve "We restrict certain activity to protect our community. Tell us if you think we made a mistake", que a Meta atribui a publicações "suspected to be spam." Isso não é problema de cota, e tentar de novo amanhã não resolve. Outras plataformas traçam a mesma linha entre uma cota que dá para esperar passar e uma restrição que não dá, e é por isso que os limites de taxa publicados do Pinterest e os do Instagram precisam de caminhos de tratamento separados na mesma fila.

De quais permissões a chamada precisa?

Os escopos do token diferem por fluxo de login, e a Meta lista os dois. A Instagram API com Instagram Login precisa de instagram_business_basic e instagram_business_content_publish. A Instagram API com Facebook Login precisa de instagram_basic, instagram_content_publish e pages_read_engagement, mais ads_management ou ads_read quando "the app user was granted a role via the Business Manager on the Page connected to the targeted IG User."

Esses são os mesmos escopos que a própria chamada de publicação exige, então um token que consegue publicar também consegue ler a cota. Não existe escopo somente de leitura mais barato para checar capacidade, o que significa que a checagem de cota está disponível para todo app que algum dia precise dela.

Perguntas frequentes

Qual é o caminho completo do endpoint?

GET /<IG_USER_ID>/content_publishing_limit, em graph.facebook.com para a Instagram API com Facebook Login e em graph.instagram.com para a Instagram API com Instagram Login.

O endpoint devolve o limite por padrão?

Não. Só quota_usage volta por padrão. A referência da Meta diz que o objeto config, que guarda quota_total e quota_duration, precisa ser pedido pelo parâmetro fields.

Até onde o parâmetro since consegue voltar?

24 horas. A Meta descreve o valor como "A Unix timestamp no older than 24 hours", então o endpoint não consegue reportar uso de nenhuma janela anterior.

Tentativas de publicação que falharam contam contra o quota_usage?

A Meta não diz. O campo conta as vezes em que o usuário "has published an IG Container", o que se lê como publicações bem-sucedidas, mas a documentação nunca trata de uma publicação que dá erro depois de ter sido aceita.

Criar um container de mídia consome cota?

Não. A criação de containers é governada por uma regra separada, a de que uma conta "can only create 400 containers within a rolling 24 hour period", e containers expiram depois de 24 horas sendo publicados ou não.

Por que o quota_total diz 50 quando o guia diz 100?

A Meta publica os dois números e nunca os resolve. A referência do endpoint diz que quota_total é "currently 50", o guia de publicação de conteúdo diz 100 na seção de limite de taxa e 50 de novo na seção de carrossel. Leia o valor da resposta em vez de confiar em qualquer uma das páginas.

Com que frequência você deve reconferir a cota em uma fila de publicação?

Reconfira antes de cada publicação da fila, não só uma vez no início. A janela é móvel, então um lote de 20 posts que só checou a capacidade no começo pode ultrapassar o teto por volta do post 14. Comparar quota_usage com config.quota_total a cada envio pega esse desvio antes que o Instagram pegue.

Um carrossel conta como um post ou como vários contra o quota_usage?

Um carrossel conta como um único post não importa quantas imagens ele tenha, segundo a frase da Meta "Carousels count as a single post". Dez imagens publicadas juntas gastam a mesma unidade de quota_usage que uma única imagem publicada sozinha. Isso torna os carrosséis bem mais baratos contra o teto do que publicar essas mesmas imagens uma a uma.

O que acontece se um app ignorar o limite de publicação?

A Meta recomenda que os apps apliquem o limite de frequência por conta própria, principalmente quando permitem agendar posts com antecedência, porque pular a checagem só adia a falha até a hora de publicar. Uma conta acima da cota recebe HTTP 400, código 9, subcódigo 2207042, e a capacidade volta 24 horas depois de cada publicação, não em uma redefinição diária. Uma ferramenta de agendamento que pula essa checagem prévia descobre isso depois de já ter se comprometido com um horário de publicação que não consegue mais cumprir.

Uma restrição por spam é a mesma coisa que bater no teto de publicação?

Uma restrição por spam é uma falha diferente de um limite de cota. O código 4, subcódigo 2207051, aparece quando uma publicação é "suspected to be spam", e tentar de novo no dia seguinte não resolve o problema como esperar a cota resolve. Essa diferença importa numa fila, porque os dois erros precisam de caminhos de tratamento separados, um que espera e outro que para e sinaliza o conteúdo.