Skip to main content
As APIs v2 estão em alpha e podem mudar a qualquer momento.

​
Visão geral

A Analytics API v2 é a próxima geração da Devin Desktop Analytics API. Ela expõe análises de consumo (créditos e ACUs) por meio de endpoints REST claros, com filtragem por parâmetros de consulta, agrupamento flexível, paginação baseada em cursor e cache de respostas.
No momento, os endpoints da v2 são disponibilizados sob o prefixo /api/v2alpha enquanto a API é finalizada. A URL base é https://server.codeium.com.

​
O que há de novo na v2

A maior mudança em relação à v1 é a autenticação.

​
Autenticação

A v2 usa autenticação com token Bearer. Passe sua credencial no cabeçalho Authorization, em vez de enviá-la no corpo da requisição:
São aceitos dois tipos de credenciais: uma chave de API de usuário de serviço do Devin (recomendada — a mesma chave cog_ que você usa na Devin API) ou uma chave de serviço do Windsurf.

​
Chaves de API de usuários de serviço do Devin

Se você já gerencia usuários de serviço do Devin, não precisa de credenciais separadas para o Windsurf:
  1. Crie um usuário de serviço em Configurações > Usuários de serviço (organização) ou Configurações do Enterprise > Usuários de serviço (Enterprise)
  2. Atribua a ele uma função personalizada que inclua a permissão Usar API de análises local (a função de administrador nativa já a inclui)
  3. Gere uma chave de API para o usuário de serviço — ela começa com cog_
  4. Use essa chave como token Bearer
Os resultados abrangem toda a conta do Devin à qual o usuário de serviço pertence, e metadata.team_id é o identificador da equipe do Devin da conta (devin-team$<account_id>).
O filtro group_id é um conceito das equipes do Windsurf e não é compatível com credenciais do Devin — requisições que combinam os dois retornam 400 Bad Request.

​
Chaves de serviço do Windsurf

  1. Acesse sua página Configurações da equipe
  2. Vá para a seção “Service Keys”
  3. Crie uma nova chave de serviço com a permissão Analytics Read
  4. Use a chave como token Bearer no cabeçalho Authorization
Há suporte a chaves de serviço com escopo de grupo — quando uma chave é restrita a um grupo, os resultados são automaticamente limitados a esse grupo.
Mantenha essas credenciais seguras e nunca as exponha em código do lado do cliente ou em repositórios públicos.

​
Endpoints disponíveis

​
Estratégia de faturamento

As respostas se adaptam à estratégia de faturamento da sua equipe, informada em metadata.billing_strategy:
  • CREDITS — as linhas incluem prompt_credits e flex_credits
  • ACU — as linhas incluem billed_acus
O campo message_count é sempre retornado, independentemente da estratégia. As respostas de listagem são paginadas. Quando houver mais dados disponíveis, a resposta incluirá um pagination.next_page_cursor; passe-o novamente como o parâmetro de consulta page_cursor para obter a próxima página. Os cursores expiram após 24 horas.

​
Cache

As respostas incluem o cabeçalho ETag. Envie-o de volta no cabeçalho If-None-Match em requisições subsequentes para receber um 304 Not Modified quando os dados não forem alterados.

​
Limites de taxa

Estes endpoints não se destinam 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-os para relatórios periódicos e exportações em massa, não para dashboards em tempo real nem acompanhamento por requisição.
Os endpoints v2 estão limitados a 10 requisições por hora por equipe. Exceder o limite retorna 429 Too Many Requests com um cabeçalho Retry-After. Paginar uma consulta anterior (seguindo um next_page_cursor) não conta para o limite de taxa — apenas a consulta inicial de cada relatório conta. O limite baixo reflete que esses endpoints se destinam a relatórios periódicos, não ao monitoramento em tempo real.