> ## 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.
# Consultar usuários ativos
> Consulte o número de usuários ativos distintos da sua equipe, com granularidade temporal opcional e agrupamento por usuário.
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](#authentication) 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
```
A chave de serviço deve ter a permissão **Leitura de análises**. Crie uma em [Configurações da equipe](https://windsurf.com/team/settings), 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.
As contagens de usuários ativos incluem o uso do **Devin CLI e do Devin Desktop**. Um usuário que
esteja ativo em qualquer um deles (ou em ambos) é contabilizado apenas uma vez por intervalo de tempo.
## 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](/pt-BR/desktop/accounts/api-reference/get-consumption), 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.
## OpenAPI
````yaml pt-BR/desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/active-users
openapi: 3.1.0
info:
title: Devin Desktop Analytics API v2
version: 2.0.0
description: >
A Analytics API v2 fornece análises de consumo de créditos e ACU para
equipes Enterprise.
Os dados são obtidos de eventos de faturamento agregados por hora e oferecem
suporte a filtragem, agrupamento
e paginação baseada em cursor.
servers:
- url: https://server.codeium.com
security:
- bearerAuth: []
paths:
/api/v2alpha/analytics/active-users:
get:
summary: Obter análises de usuários ativos
description: >
Consulte o número de usuários ativos distintos da equipe autenticada. Um
usuário é contado como
ativo em um período se tiver qualquer evento de faturamento nele. Os
resultados são obtidos de
eventos de faturamento agregados por hora e podem ser filtrados por
intervalo de datas, produto, modelo e grupo.
Use `granularity` para detalhar a contagem por dia ou mês e
`group_by=user` para retornar uma
linha por usuário (o `active_users` de cada linha será `1`).
As respostas são armazenadas em cache por 1 hora. Use `If-None-Match`
com um `ETag` retornado anteriormente para
receber um `304 Not Modified` quando os dados não tiverem sido
alterados.
Esses endpoints foram projetados para relatórios periódicos e exportação
em massa. **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).
operationId: getActiveUsers
parameters:
- name: start_date
in: query
required: true
schema:
type: string
format: date
description: Início do intervalo de datas (inclusive), no formato `YYYY-MM-DD`.
example: '2026-01-01T00:00:00.000Z'
- name: end_date
in: query
required: true
schema:
type: string
format: date
description: >-
Fim do intervalo de datas (inclusive), no formato `YYYY-MM-DD`. O
intervalo não deve exceder 90 dias.
example: '2026-01-31T00:00:00.000Z'
- name: product
in: query
required: true
schema:
type: string
enum:
- agent
description: Produto para consultar usuários ativos.
example: agent
- name: granularity
in: query
required: false
schema:
type: string
enum:
- daily
- monthly
description: >
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.
- name: group_by
in: query
required: false
schema:
type: string
enum:
- user
description: >
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`).
example: user
- name: models
in: query
required: false
schema:
type: string
description: >-
Lista de UIDs de modelo, separada por vírgulas, para filtrar os
resultados.
example: claude-4-sonnet,gpt-4.1
- name: group_id
in: query
required: false
schema:
type: string
description: >-
Filtre os resultados para usuários em um grupo específico. A service
key deve ter acesso a esse grupo.
- name: user_id
in: query
required: false
schema:
type: string
description: >-
Filtre os resultados para um usuário específico (UID de
autenticação).
- name: page_size
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 1000
description: Número máximo de linhas a serem retornadas por página.
- name: page_cursor
in: query
required: false
schema:
type: string
description: >-
Cursor opaco de `pagination.next_page_cursor` de uma resposta
anterior para buscar a página seguinte.
- name: If-None-Match
in: header
required: false
schema:
type: string
description: >-
Valor de ETag de uma resposta anterior. Se os dados não tiverem sido
alterados, o servidor retornará `304 Not Modified`.
responses:
'200':
description: Dados de usuários ativos retornados com sucesso.
headers:
ETag:
schema:
type: string
description: >-
Tag de entidade para validação de cache. Passe-a como
`If-None-Match` em requisições subsequentes.
Cache-Control:
schema:
type: string
description: Diretiva de cache (por exemplo, `private, max-age=3600`).
content:
application/json:
schema:
$ref: '#/components/schemas/ActiveUsersResponse'
examples:
aggregate:
summary: Total de usuários ativos no intervalo de datas
value:
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
daily:
summary: Usuários ativos por dia
value:
data:
- timestamp: '2026-01-15T00:00:00.000Z'
active_users: 138
- timestamp: '2026-01-16T00:00:00.000Z'
active_users: 145
pagination:
next_page_cursor: null
metadata:
data_freshness: '2026-01-16T03:00:00.000Z'
query_time_ms: 734
team_id: team_abc123
by_user:
summary: Agrupado por usuário
value:
data:
- user_id: user_abc123
active_users: 1
- user_id: user_def456
active_users: 1
pagination:
next_page_cursor: null
metadata:
data_freshness: '2026-01-16T03:00:00.000Z'
query_time_ms: 845
team_id: team_abc123
'304':
description: >-
Os dados não foram alterados desde a ETag fornecida em
`If-None-Match`.
'400':
description: Parâmetros de requisição inválidos.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_param:
value:
error: start_date is required
bad_group_by:
value:
error: 'unsupported group_by dimension for active-users: model_uid'
bad_product:
value:
error: 'unsupported product: foo (supported: agent)'
'401':
description: Falha na autenticação ou permissões insuficientes.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_auth:
value:
error: missing Authorization header
invalid_key:
value:
error: invalid service key
insufficient_permissions:
value:
error: insufficient permissions
'403':
description: >-
O cursor de página fornecido não pertence à equipe autenticada nem
ao grupo solicitado.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
cursor_team_mismatch:
value:
error: page cursor does not belong to this team
'405':
description: Método HTTP não permitido (há suporte apenas para `GET`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: >-
Limite de taxa excedido (10 requisições por hora por equipe).
Paginar uma consulta anterior não conta para esse limite.
headers:
Retry-After:
schema:
type: string
description: Tempo de espera sugerido antes de tentar novamente.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limited:
value:
error: rate limit exceeded
'503':
description: >-
O serviço de análises não está disponível (por exemplo, em
implantações auto-hospedadas).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth: []
components:
schemas:
ActiveUsersResponse:
type: object
required:
- data
- pagination
- metadata
properties:
data:
type: array
items:
$ref: '#/components/schemas/ActiveUsersRow'
description: Array de linhas de dados de usuários ativos.
pagination:
type: object
properties:
next_page_cursor:
type:
- string
- 'null'
description: >
Cursor opaco para buscar a próxima página de resultados. Passe
esse valor como parâmetro de consulta `page_cursor`
em uma requisição seguinte. `null` quando não houver mais
páginas.
Os cursores de página expiram após 24 horas.
metadata:
type: object
properties:
data_freshness:
type: string
format: date-time
description: >-
Timestamp que indica quando os dados subjacentes foram
atualizados pela última vez (truncado para a hora).
query_time_ms:
type: integer
format: int64
description: Tempo de execução da consulta no servidor, em milissegundos.
team_id:
type: string
description: O ID da equipe resolvido a partir da service key autenticada.
group_id:
type: string
description: >-
O ID do grupo ao qual os resultados foram limitados. Presente
apenas quando `group_id` foi fornecido.
Error:
type: object
required:
- error
properties:
error:
type: string
description: Mensagem de erro legível por humanos.
ActiveUsersRow:
type: object
required:
- active_users
properties:
timestamp:
type: string
description: >
Intervalo de tempo da linha. O formato depende de `granularity`:
`YYYY-MM-DD` para diário, `YYYY-MM` para mensal.
Presente apenas quando `granularity` é especificado.
examples:
- '2026-05-01T00:00:00.000Z'
- 2026-05
user_id:
type: string
description: >-
Identificador do usuário (UID de autenticação). Presente apenas
quando `group_by` inclui `user`.
active_users:
type: integer
format: int64
description: >
Contagem de usuários ativos distintos na linha. Um usuário é contado
como ativo em um intervalo de tempo se
tiver qualquer evento de faturamento nele. Quando agrupado por
`user`, isso é sempre `1`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
Uma service key com permissão **Analytics Read**, enviada como token
Bearer no header `Authorization`.
Crie uma service key em [Configurações da
equipe](https://windsurf.com/team/settings), na seção "Service Keys".
````