FlowData

Como consulto o uso, as tarefas e o estado do processamento de mídia pela API?

Publicado em 10. novembro 2026

Além de iniciar tarefas, o processamento de mídia oferece alguns endpoints para a sua aplicação manter o controle: obter os números do mês, reencontrar tarefas pela sua própria referência, cancelar uma tarefa e verificar se o processamento está funcionando normalmente.

Consultando o uso de um período

GET /v1/media/usage retorna os números da sua equipe em um período. Sem parâmetros, vale o mês atual até hoje. Com from e to no formato AAAA-MM-DD, você escolhe o período, e os dois dias contam.

curl "https://api.flowdata.one/v1/media/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer fd_SUA_CHAVE"
{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "jobs": 148,
  "failed": 3,
  "processing_seconds": 9412.6,
  "input_bytes": 31845120384,
  "by_pipeline": {"chat_video": 92, "chat_image": 41, "course_video": 15}
}

Os números do exemplo são inventados.

  • jobs: número de tarefas criadas no período.
  • failed: quantas delas falharam.
  • processing_seconds: tempo total de processamento em segundos.
  • input_bytes: tamanho somado de todos os arquivos de entrada em bytes.
  • by_pipeline: número de tarefas por pipeline.

Esses números descrevem tarefas, não valores. Quanto as tarefas custaram você vê no FlowData em Cobrança, veja Cobrança, saldo e limite de gastos do FlowData.

Se from for posterior a to ou o formato da data estiver errado, você recebe HTTP 422 com o código validation_failed.

Encontrando tarefas pela sua referência

Se você informar uma reference ao iniciar uma tarefa, como um número de pedido ou de produto, pode reencontrar todas as tarefas dela:

curl "https://api.flowdata.one/v1/media/jobs?reference=order:4711" \
  -H "Authorization: Bearer fd_SUA_CHAVE"

A resposta traz em data as até 20 tarefas mais recentes com exatamente essa referência, da mais nova para a mais antiga. Cada item tem o mesmo formato de GET /v1/media/jobs/{id}. Sem reference, ou com mais de 191 caracteres, a API responde com HTTP 422. Não há listagem de todas as tarefas sem referência pela API. Elas estão no FlowData em Tarefas, onde você também pode buscar pela sua referência.

Consultando ou cancelando uma tarefa

  • GET /v1/media/jobs/{id} retorna uma tarefa da sua equipe. Para tarefas de outras equipes e IDs desconhecidos, a API responde com HTTP 404.
  • DELETE /v1/media/jobs/{id} cancela imediatamente uma tarefa em espera e solicita o cancelamento de uma em andamento. A resposta é a tarefa no novo estado.

O que acontece exatamente no cancelamento está em Como acompanho o status das minhas tarefas de mídia?.

Verificando se o processamento de mídia está funcionando

GET /v1/media/health não precisa de chave. Você pode incluí-lo no seu monitoramento, por exemplo:

curl "https://api.flowdata.one/v1/media/health"
{"status":"ok","queue":{"pending":2,"processing":1},"version":"1.0.0"}
  • status: ok quando tudo funciona normalmente. degraded significa que o processamento de mídia está limitado, por exemplo durante uma manutenção anunciada ou quando o processamento de imagens não está disponível no momento. Com down, nenhuma tarefa está sendo processada agora.
  • queue.pending, queue.processing: tarefas em espera e em andamento em toda a plataforma, não só na sua equipe. Uma fila longa explica por que uma tarefa começa mais tarde.
  • version: a versão do processamento de mídia.

Bom saber

  • Os endpoints com chave contam, como todas as requisições do processamento de mídia, para o limite de 600 requisições por minuto por chave. Por isso, não consulte o estado de uma tarefa a cada segundo. Os webhooks, que avisam sozinhos, são mais práticos, veja Como configuro webhooks para o processamento de mídia?.
  • Todos os erros do processamento de mídia têm o formato {"error":{"code":"...","message":"...","details":{...},"type":"..."}}.

Este artigo foi útil?

Voltar para Processamento de mídia