Em Consumo e Solicitações, você vê na interface o que suas aplicações consumiram. Se quiser levar esses números para seus próprios relatórios, sua contabilidade ou um dashboard, use os dois endpoints GET /usage e GET /usage/requests. Caso típico: você repassa os custos por cliente aos seus próprios clientes.
Resumo: GET /usage
GET /v1/usage resume requisições, tokens e custos de um período.
curl "https://api.flowmodels.one/v1/usage?start=2026-10-01&end=2026-10-31&group_by=end_user" \
-H "Authorization: Bearer at_sua_chave"
starteendsão dias no formatoAAAA-MM-DD. Sem indicação, você recebe os últimos 30 dias até hoje.group_bydefine a divisão:day(padrão),model,api_keyouend_user.
{
"object": "list",
"data": [
{"bucket": "cliente-1042", "requests": 128, "prompt_tokens": 61240, "completion_tokens": 18410, "total_tokens": 79650, "cost_micro_eur": 1840000}
],
"start": "2026-10-01",
"end": "2026-10-31",
"group_by": "end_user"
}
bucket é, conforme o agrupamento, o dia, o identificador do modelo, o UUID da chave ou seu identificador de usuário final. Requisições sem usuário final e requisições de usuários finais excluídos ficam juntas, com group_by=end_user, em uma entrada com bucket: null. Uma resposta contém no máximo 1.000 entradas, então com muitos usuários finais escolha períodos mais curtos. cost_micro_eur é o valor faturado em micro-euros, ou seja, 1.840.000 equivalem a 1,84 €.
requests conta requisições, não chamadas individuais ao provedor. Uma requisição para a qual também resumimos o histórico ou buscamos em arquivos de usuário final continua sendo uma requisição. Mas os custos dessas etapas adicionais entram em cost_micro_eur.
Requisições individuais: GET /usage/requests
GET /v1/usage/requests lista as requisições individuais, as mais recentes primeiro. Cada entrada contém:
request_id, created_at, api_key, end_user, model, provider, status, error_code, latency_ms, prompt_tokens, completion_tokens e cost_micro_eur.
provider é o provedor no qual a requisição foi de fato faturada. request_id corresponde ao flowai_request_id da resposta da sua aplicação.
Você pode filtrar com estes parâmetros:
status, por exemplosuccessapi_keycom o UUID de uma chaveend_usercom o seu identificador de usuário final, ou seja, o valor deexternal_identifiermodelcom o identificador do modelo, como enviado na requisição
Consultar página por página
Por padrão, a lista retorna 20 entradas, e com limit, até 100. Se a resposta trouxer has_more: true, busque a próxima página com after e o valor de last_id:
curl "https://api.flowmodels.one/v1/usage/requests?limit=100&end_user=cliente-1042&after=aWQ6MTIz" \
-H "Authorization: Bearer at_sua_chave"
Para uma análise completa, repita até has_more ficar como false.
Qual chave você precisa
Os dois endpoints funcionam com uma chave de permissão Usar IA e com uma chave Gerenciar chaves. Para um script de relatórios, recomendamos uma chave de gerenciamento própria, que não possa chamar modelos. Chaves da assinatura da FlowSuite são recusadas aqui com 403 insufficient_key_scope.
Nenhum conteúdo
Esses endpoints nunca retornam o texto das suas requisições nem as respostas do modelo, nem mesmo em trechos. Para esclarecer uma chamada específica, fale com o suporte informando o request_id. O que armazenamos e por quanto tempo está em Quais dados o FlowModels armazena e por quanto tempo.
Quando algo não funciona
Em caso de parâmetros incorretos, a API responde com 400 invalid_field_value e uma mensagem clara, por exemplo:
- “O parâmetro group_by aceita apenas day, model, api_key e end_user.”
- “O parâmetro start precisa ser uma data no formato AAAA-MM-DD.”
- “O parâmetro start não pode ser posterior a end.”
Prefere analisar na interface? Então use Analisar o consumo e exportar em CSV.