> ## 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.

# Obtener usuarios activos

> Consulta cuántos usuarios activos distintos hay en tu equipo, con granularidad temporal opcional y agrupación por usuario.

<Note>
  Este es un **endpoint v2** que usa autenticación con token Bearer y parámetros de consulta, a diferencia de la API de Analytics v1, que usa claves de servicio en el cuerpo de la solicitud. Consulta [Autenticación](#authentication) más abajo.
</Note>

<Warning>
  Este endpoint **no** está pensado para supervisar el uso en tiempo real. Los datos se agregan por hora y el
  límite de solicitudes es bajo (10 solicitudes por hora por equipo). Úsalo para informes periódicos y exportaciones masivas.
</Warning>

<div id="authentication">
  ## Autenticación
</div>

Este endpoint utiliza autenticación mediante **Bearer token**. Incluye tu clave de servicio en el encabezado `Authorization`:

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

La clave de servicio debe tener el permiso **Analytics Read**. Crea una en [Team Settings](https://windsurf.com/team/settings), en la sección "Service Keys".

<div id="what-counts-as-an-active-user">
  ## Qué se considera un usuario activo
</div>

Un usuario se considera **activo** en un intervalo de tiempo determinado si tiene algún evento de facturación en él. El
campo `active_users` indica el número de usuarios distintos.

<Note>
  El recuento de usuarios activos incluye el uso de **Devin CLI y Devin Desktop**. Un usuario que esté
  activo en cualquiera de los dos (o en ambos) se contabiliza, y solo se cuenta una vez por intervalo temporal.
</Note>

<div id="grouping-and-granularity">
  ## Agrupación y granularidad
</div>

Usa `granularity` y `group_by` para controlar la estructura de los datos devueltos:

* **Sin granularidad ni agrupación** — devuelve una sola fila con el recuento total de usuarios activos para todo el intervalo de fechas
* **`granularity=daily`** — cada fila incluye un `timestamp` en formato `YYYY-MM-DD` (usuarios activos diarios)
* **`granularity=monthly`** — cada fila incluye un `timestamp` en formato `YYYY-MM` (usuarios activos mensuales)
* **`group_by=user`** — devuelve una fila por cada usuario activo con un `user_id`; el valor de `active_users` en cada fila es `1`

<Note>
  A diferencia de [Obtener consumo](/es/desktop/accounts/api-reference/get-consumption), el endpoint de usuarios activos
  solo admite `user` como valor de `group_by`. Otras dimensiones (`model_uid`, `ide`) no son válidas aquí.
</Note>

<div id="pagination">
  ## Paginación
</div>

Los resultados se paginan con un tamaño de página predeterminado de 1.000 filas (máx. 10.000). Cuando hay más resultados disponibles,
la respuesta incluye un `next_page_cursor` en el objeto `pagination`. Pásalo como parámetro de consulta `page_cursor`
para recuperar la página siguiente.

Los cursores de página caducan después de 24 horas. Una solicitud posterior de página no cuenta como una nueva consulta para tu límite de solicitudes.

<div id="caching">
  ## Almacenamiento en caché
</div>

Las respuestas incluyen un encabezado `ETag`. Para evitar transferencias de datos redundantes, incluye el encabezado `If-None-Match`
con el valor `ETag` anterior; el servidor devolverá `304 Not Modified` si los datos no han cambiado.

<div id="rate-limits">
  ## Límites de velocidad
</div>

Este endpoint está sujeto a un límite de **10 solicitudes por hora** por equipo. Si supera este límite, el
servidor devuelve `429 Too Many Requests` con un encabezado `Retry-After`.

Paginar una consulta previa (siguiendo un `next_page_cursor`) **no** se contabiliza dentro de este límite:
solo se contabiliza la consulta inicial de cada informe. El límite reducido refleja que este endpoint es para
informes periódicos, no para el seguimiento del uso en tiempo real.


## OpenAPI

````yaml es/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: >
    La Analytics API v2 proporciona analíticas de consumo de créditos y ACU para
    equipos Enterprise.

    Los datos proceden de eventos de facturación agregados por hora y admite
    filtros flexibles, agrupación

    y paginación basada en cursor.
servers:
  - url: https://server.codeium.com
security:
  - bearerAuth: []
paths:
  /api/v2alpha/analytics/active-users:
    get:
      summary: Obtener analíticas de usuarios activos
      description: >
        Consulta la cantidad de usuarios activos distintos del equipo
        autenticado. Un usuario se considera activo en un intervalo temporal si
        tiene algún evento de facturación en él. Los resultados provienen de
        eventos de facturación agregados por hora y se pueden filtrar por rango
        de fechas, producto, modelo y grupo.


        Usa `granularity` para desglosar el recuento por día o por mes, y
        `group_by=user` para devolver una fila por usuario (el valor de
        `active_users` de cada fila será `1`).


        Las respuestas se almacenan en caché durante 1 hora. Usa `If-None-Match`
        con un `ETag` devuelto previamente para recibir un `304 Not Modified`
        cuando los datos no hayan cambiado.


        Estos endpoints están diseñados para informes periódicos y exportaciones
        masivas. **No** están pensados para supervisar el uso en tiempo real:
        los datos se agregan por hora y el límite de tasa es bajo (10
        solicitudes por hora por equipo).
      operationId: getActiveUsers
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Inicio del rango de fechas (incluido) en formato `YYYY-MM-DD`.
          example: '2026-01-01T00:00:00.000Z'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: >-
            Fin del rango de fechas (incluido) en formato `YYYY-MM-DD`. El rango
            no debe superar los 90 días.
          example: '2026-01-31T00:00:00.000Z'
        - name: product
          in: query
          required: true
          schema:
            type: string
            enum:
              - agent
          description: Producto cuyos usuarios activos se consultarán.
          example: agent
        - name: granularity
          in: query
          required: false
          schema:
            type: string
            enum:
              - daily
              - monthly
          description: >
            Granularidad temporal para agrupar los resultados. Cuando se
            especifica, cada fila incluye un campo `timestamp`.

            Si se omite, el recuento de usuarios activos se agrega para todo el
            rango de fechas.
        - name: group_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - user
          description: >
            Dimensión por la que se agrupan los resultados. El endpoint de
            usuarios activos solo admite `user`, que devuelve

            una fila por cada usuario activo (cada una con `active_users` =
            `1`).
          example: user
        - name: models
          in: query
          required: false
          schema:
            type: string
          description: >-
            Lista separada por comas de UID de modelos para filtrar los
            resultados.
          example: claude-4-sonnet,gpt-4.1
        - name: group_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtra los resultados para incluir solo usuarios de un grupo
            específico. La clave de servicio debe tener acceso a este grupo.
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtra los resultados para un usuario específico (UID de
            autenticación).
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
          description: Número máximo de filas que se devuelven por página.
        - name: page_cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Cursor opaco de `pagination.next_page_cursor` de una respuesta
            anterior para obtener la página siguiente.
        - name: If-None-Match
          in: header
          required: false
          schema:
            type: string
          description: >-
            Valor de ETag de una respuesta anterior. Si los datos no han
            cambiado, el servidor devuelve `304 Not Modified`.
      responses:
        '200':
          description: Los datos de usuarios activos se devolvieron correctamente.
          headers:
            ETag:
              schema:
                type: string
              description: >-
                Etiqueta de entidad para validar la caché. Pásala como
                `If-None-Match` en solicitudes posteriores.
            Cache-Control:
              schema:
                type: string
              description: Directiva de caché (p. ej., `private, max-age=3600`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveUsersResponse'
              examples:
                aggregate:
                  summary: Total de usuarios activos en el intervalo de fechas
                  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: Usuarios activos diarios
                  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 usuario
                  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: >-
            Los datos no han cambiado desde el ETag proporcionado en
            `If-None-Match`.
        '400':
          description: Parámetros de solicitud no vá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: La autenticación falló o los permisos son 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: >-
            El cursor de página proporcionado no pertenece al equipo autenticado
            ni al 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 no permitido (solo se admite `GET`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Se superó el límite de tasa (10 solicitudes por hora por equipo).
            Paginar una consulta anterior no cuenta para este límite.
          headers:
            Retry-After:
              schema:
                type: string
              description: Tiempo de espera sugerido antes de volver a intentarlo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: rate limit exceeded
        '503':
          description: >-
            El servicio de analítica no está disponible (p. ej., en despliegues
            autohospedados).
          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 filas de datos de usuarios activos.
        pagination:
          type: object
          properties:
            next_page_cursor:
              type:
                - string
                - 'null'
              description: >
                Cursor opaco para recuperar la siguiente página de resultados.
                Pasa este valor como parámetro de consulta `page_cursor`

                en una solicitud posterior. `null` cuando no hay más páginas.

                Los cursores de página caducan al cabo de 24 horas.
        metadata:
          type: object
          properties:
            data_freshness:
              type: string
              format: date-time
              description: >-
                Marca de tiempo que indica cuándo se actualizaron por última vez
                los datos subyacentes (truncada a la hora).
            query_time_ms:
              type: integer
              format: int64
              description: >-
                Tiempo de ejecución de la consulta en el servidor, en
                milisegundos.
            team_id:
              type: string
              description: >-
                El ID del equipo resuelto a partir de la clave de servicio
                autenticada.
            group_id:
              type: string
              description: >-
                El ID del grupo al que se limitaron los resultados. Solo está
                presente cuando se proporcionó `group_id`.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Mensaje de error legible por humanos.
    ActiveUsersRow:
      type: object
      required:
        - active_users
      properties:
        timestamp:
          type: string
          description: >
            Intervalo temporal de la fila. El formato depende de `granularity`:
            `YYYY-MM-DD` para diario, `YYYY-MM` para mensual.

            Solo está presente cuando se especifica `granularity`.
          examples:
            - '2026-05-01T00:00:00.000Z'
            - 2026-05
        user_id:
          type: string
          description: >-
            Identificador de usuario (UID de autenticación). Solo está presente
            cuando `group_by` incluye `user`.
        active_users:
          type: integer
          format: int64
          description: >
            Cantidad de usuarios activos distintos en la fila. Un usuario se
            cuenta como activo en un intervalo temporal si

            tiene algún evento de facturación en él. Cuando se agrupa por
            `user`, esto siempre es `1`.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Una clave de servicio con el permiso **Analytics Read**, pasada como
        token Bearer en el encabezado `Authorization`.


        Crea una clave de servicio en tu [configuración del
        equipo](https://windsurf.com/team/settings), en la sección "Service
        Keys".

````