Pular para o conteúdo principal
GET
/
api
/
v2alpha
/
analytics
/
consumption
Obter análises de consumo
curl --request GET \
  --url https://server.codeium.com/api/v2alpha/analytics/consumption \
  --header 'Authorization: Bearer <token>'
{ "data": [ { "timestamp": "2026-01-15T00:00:00.000Z", "user_id": "user_abc123", "user_email": "alice@example.com", "consumption": { "prompt_credits": 1250, "flex_credits": 340, "message_count": 87 } }, { "timestamp": "2026-01-15T00:00:00.000Z", "user_id": "user_def456", "user_email": "bob@example.com", "consumption": { "prompt_credits": 980, "flex_credits": 150, "message_count": 52 } } ], "pagination": { "next_page_cursor": null }, "metadata": { "billing_strategy": "CREDITS", "data_freshness": "2026-01-16T03:00:00.000Z", "query_time_ms": 1423, "team_id": "team_abc123" } }
Este é um endpoint v2 que usa autenticação com token Bearer e parâmetros de consulta, ao contrário da Analytics API v1, que usa chaves de serviço no corpo da requisição. Veja Autenticação abaixo.
Este endpoint não se destina ao monitoramento de uso em tempo real. Os dados são agregados por hora, e o limite de taxa é baixo (10 requisições por hora por equipe). Use-o para relatórios periódicos e exportação em massa.

​
Autenticação

Este endpoint usa autenticação com token Bearer. Inclua sua chave de serviço no cabeçalho Authorization: 
Authorization: Bearer <your_service_key>
A chave de serviço deve ter a permissão Leitura de análises. Crie uma nas Configurações da equipe, em “Service Keys”.

​
Estratégia de faturamento

A estrutura da resposta depende da estratégia de faturamento da sua equipe:
EstratégiaCampos preenchidosDescrição
CREDITSprompt_credits, flex_creditsequipes Standard Enterprise SaaS
ACUbilled_acusequipes faturadas por ACUs
O campo message_count (dentro de consumption) é sempre preenchido, independentemente da estratégia de faturamento.

​
Agrupamento e granularidade

Use granularity e group_by para controlar o formato dos dados retornados:
  • Sem granularidade nem agrupamento — retorna uma única linha agregada para todo o intervalo de datas
  • granularity=daily — cada linha inclui um timestamp no formato YYYY-MM-DD
  • granularity=monthly — cada linha inclui um timestamp no formato YYYY-MM
  • group_by=user — cada linha inclui user_id e user_email
  • group_by=user,model_uid — cada linha inclui user_id, user_email e model_uid
  • group_by=ide — cada linha inclui ide
Os resultados são paginados com um tamanho de página padrão de 1.000 linhas (máx. 10.000). Quando houver mais resultados disponíveis, a resposta incluirá um next_page_cursor no objeto pagination. Passe-o como parâmetro de query page_cursor para obter a próxima página. Os cursores de página expiram após 24 horas. Uma requisição subsequente de página não conta como uma nova consulta para o seu limite de taxa.

​
Cache

As respostas incluem um cabeçalho ETag. Para evitar transferência desnecessária de dados, inclua o cabeçalho If-None-Match com o valor anterior de ETag — o servidor retornará 304 Not Modified se os dados não tiverem sido alterados.

​
Limites de taxa

Este endpoint tem um limite de 10 requisições por hora por equipe. Se você exceder esse limite, o servidor retornará 429 Too Many Requests com um cabeçalho Retry-After. Paginar uma consulta anterior (seguindo um next_page_cursor) não entra nesse limite — apenas a consulta inicial de cada relatório entra. Esse limite baixo reflete o fato de que este endpoint é para relatórios periódicos, não para monitoramento de uso em tempo real.

Autorizações

​
Authorization
string
header
obrigatório

Uma service key com permissão Analytics Read, enviada como token Bearer no header Authorization.

Crie uma service key em Configurações da equipe, na seção "Service Keys".

Cabeçalhos

​
If-None-Match
string

Valor de ETag de uma resposta anterior. Se os dados não tiverem sido alterados, o servidor retornará 304 Not Modified.

Parâmetros de consulta

​
start_date
string<date>
obrigatório

Início do intervalo de datas (inclusive), no formato YYYY-MM-DD.

​
end_date
string<date>
obrigatório

Fim do intervalo de datas (inclusive), no formato YYYY-MM-DD. O intervalo não deve exceder 90 dias.

​
product
enum<string>
obrigatório

Produto para consultar o consumo.

Opções disponíveis:
agent
​
granularity
enum<string>

Granularidade de tempo para agrupar os resultados. Quando especificada, cada linha inclui um campo timestamp. Se omitida, os resultados são agregados em todo o intervalo de datas.

Opções disponíveis:
daily,
monthly
​
group_by
string

Lista de dimensões, separadas por vírgulas, para agrupar os resultados. Dimensões compatíveis:

  • user — inclui user_id e user_email em cada linha
  • model_uid — inclui model_uid em cada linha
  • ide — inclui ide em cada linha
​
models
string

Lista de UIDs de modelo, separados por vírgulas, para filtrar os resultados.

​
group_id
string

Filtre os resultados para usuários de um grupo específico. A service key deve ter acesso a esse grupo.

​
user_id
string

Filtre os resultados para um usuário específico (UID de autenticação).

​
page_size
integer
padrão:1000

Número máximo de linhas a retornar por página.

Intervalo obrigatório: 1 <= x <= 10000
​
page_cursor
string

Cursor opaco de pagination.next_page_cursor de uma resposta anterior para buscar a próxima página.

Resposta

Dados de consumo retornados com sucesso.

​
data
object[]
obrigatório

Array de linhas de dados de consumo.

​
pagination
object
obrigatório
​
metadata
object
obrigatório