Pular para o conteúdo principal
GET
/
api
/
v2alpha
/
analytics
/
active-users
Obter análises de usuários ativos
curl --request GET \
  --url https://server.codeium.com/api/v2alpha/analytics/active-users \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "active_users": 142
    }
  ],
  "pagination": {
    "next_page_cursor": null
  },
  "metadata": {
    "data_freshness": "2026-01-16T03:00:00.000Z",
    "query_time_ms": 612,
    "team_id": "team_abc123"
  }
}
Este é um endpoint v2 que usa autenticação com token Bearer e parâmetros de consulta, diferentemente da Analytics API v1, que usa chaves de serviço no corpo da requisição. Consulte 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 de requisições é 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 em Configurações da equipe, em “Chaves de serviço”.

​
O que conta como um usuário ativo

Um usuário é considerado ativo em um determinado intervalo de tempo se tiver qualquer evento de cobrança nele. O campo active_users informa o número de usuários distintos.

​
Agrupamento e granularidade

Use granularity e group_by para controlar o formato dos dados retornados:
  • Sem granularidade nem agrupamento — retorna uma única linha com a contagem total de usuários ativos em todo o intervalo de datas
  • granularity=daily — cada linha inclui um timestamp no formato YYYY-MM-DD (usuários ativos diários)
  • granularity=monthly — cada linha inclui um timestamp no formato YYYY-MM (usuários ativos mensais)
  • group_by=user — retorna uma linha por usuário ativo com um user_id; o active_users de cada linha é 1
Diferentemente de Consultar consumo, o endpoint de usuários ativos oferece suporte apenas a user em group_by. Outras dimensões (model_uid, ide) não são válidas aqui.
Os resultados são paginados com um tamanho de página padrão de 1.000 linhas (máx. 10.000). Quando há mais resultados disponíveis, a resposta inclui um next_page_cursor no objeto pagination. Passe-o como parâmetro de consulta page_cursor para buscar a próxima página. Os cursores de página expiram após 24 horas. Uma requisição de página subsequente não conta como uma nova consulta para fins do seu limite de taxa de requisições.

​
Cache

As respostas incluem um cabeçalho ETag. Para evitar transferências redundantes 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 de requisições

Este endpoint tem um limite de taxa de requisições 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 conta para esse limite — apenas a consulta inicial de cada relatório conta. O limite baixo reflete o fato de que este endpoint é destinado a relatórios periódicos, não ao 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 usuários ativos.

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, a contagem de usuários ativos é agregada em todo o intervalo de datas.

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

Dimensão pela qual os resultados devem ser agrupados. O endpoint de usuários ativos oferece suporte apenas a user, que retorna uma linha por usuário ativo (cada uma com active_users = 1).

Opções disponíveis:
user
​
models
string

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

​
group_id
string

Filtre os resultados para usuários em 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 serem retornadas 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 página seguinte.

Resposta

Dados de usuários ativos retornados com sucesso.

​
data
object[]
obrigatório

Array de linhas de dados de usuários ativos.

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