> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API v2

> API de análises de nova geração para consultar dados de consumo com autenticação via token Bearer, agrupamento flexível e paginação por cursor.

<Warning>
  As APIs v2 estão em **alpha** e podem mudar a qualquer momento.
</Warning>

<div id="overview">
  ## Visão geral
</div>

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.

<Note>
  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`.
</Note>

<div id="whats-new-in-v2">
  ## O que há de novo na v2
</div>

A maior mudança em relação à [v1](/pt-BR/desktop/accounts/api-reference/analytics-api-introduction) é a **autenticação**.

|              | Analytics API v1                               | Analytics API v2                                       |
| ------------ | ---------------------------------------------- | ------------------------------------------------------ |
| Transporte   | `POST` com um corpo de requisição JSON         | `GET` com parâmetros de consulta                       |
| Autenticação | Campo `service_key` **no corpo da requisição** | **cabeçalho `Authorization: Bearer <service_key>`**    |
| Permissão    | Varia conforme o endpoint                      | **Analytics Read**                                     |
| Paginação    | Nenhuma                                        | Baseada em cursor (`next_page_cursor` / `page_cursor`) |
| Cache        | Nenhum                                         | `ETag` + `If-None-Match` (`304 Not Modified`)          |

<div id="authentication">
  ## Autenticação
</div>

A v2 usa autenticação com **token Bearer**. Passe sua chave de serviço no cabeçalho `Authorization`, em vez
de enviá-la no corpo da requisição:

```
Authorization: Bearer <your_service_key>
```

A chave de serviço deve ter a permissão **Analytics Read**.

<div id="creating-a-service-key">
  ### Criando uma chave de serviço
</div>

1. Acesse sua [página Configurações da equipe](https://windsurf.com/team/settings)
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`

<Warning>Mantenha suas chaves de serviço seguras e nunca as exponha em código do lado do cliente ou em repositórios públicos.</Warning>

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.

<div id="available-endpoints">
  ## Endpoints disponíveis
</div>

| Endpoint                                                                                                                    | Descrição                                                                                     |
| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [Obter consumo](/pt-BR/desktop/accounts/api-reference/get-consumption) (`GET /api/v2alpha/analytics/consumption`)           | Consultar o consumo de créditos ou ACUs com filtragem, agrupamento, granularidade e paginação |
| [Obter usuários ativos](/pt-BR/desktop/accounts/api-reference/get-active-users) (`GET /api/v2alpha/analytics/active-users`) | Contar usuários ativos distintos, opcionalmente por dia/mês ou por usuário                    |

<div id="billing-strategy">
  ## Estratégia de faturamento
</div>

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.

<div id="pagination">
  ## Paginação
</div>

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.

<div id="caching">
  ## Cache
</div>

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.

<div id="rate-limits">
  ## Limites de taxa
</div>

<Warning>
  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.
</Warning>

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.