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

# SDK de Python

> Consulta analíticas y gestiona grupos y límites de ACU desde la línea de comandos con el SDK de Python.

<Info>
  Esta documentación corresponde a los despliegues federales de Devin. [Volver a la documentación de Devin](/es/get-started/devin-intro)
</Info>

El SDK de Python (`windsurf_analytics.py`) es un cliente de línea de comandos para los endpoints de la [API federal](/es/federal/api/overview): informes de uso, [consumo de ACU](/es/federal/api/acu-consumption), [gestión de grupos](/es/federal/api/group-management) y [límites de ACU por usuario](/es/federal/api/acu-caps). Ponte en contacto con tu representante de Cognition para obtener el script de tu despliegue.

<div id="requirements">
  ## Requisitos
</div>

* Python 3
* La biblioteca `requests`: `pip install requests`

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

Todos los comandos aceptan estas opciones compartidas:

| Opción          | Descripción                                                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--service-key` | Clave de servicio para la autenticación. También se puede configurar mediante la variable de entorno `WINDSURF_SERVICE_KEY`. |
| `--api-url`     | URL base del servidor de API de tu despliegue (`https://<your-server>`). Se requiere HTTPS.                                  |

El rol de la clave de servicio debe contar con el permiso requerido por cada comando; consulta la [tabla de permisos](/es/federal/api/overview#required-permissions). Todos los comandos de analytics también requieren un tier de equipo con acceso a la Analytics API.

<div id="commands">
  ## Comandos
</div>

| Comando                  | Endpoint                                   | Permiso requerido     |
| ------------------------ | ------------------------------------------ | --------------------- |
| `usage` (predeterminado) | `/UserPageAnalytics` + `/CascadeAnalytics` | Teams de solo lectura |
| `acu-consumption`        | `/Analytics`                               | Analytics Read        |
| `list-groups`            | `/ListGroups`                              | Teams de solo lectura |
| `get-group`              | `/GetGroup`                                | Teams de solo lectura |
| `create-group`           | `/CreateGroup`                             | Teams Update          |
| `update-group`           | `/UpdateGroup`                             | Teams Update          |
| `delete-group`           | `/DeleteGroup`                             | Teams Update          |
| `list-group-members`     | `/ListGroupMembers`                        | Teams de solo lectura |
| `add-group-members`      | `/AddGroupMembers`                         | Teams Update          |
| `remove-group-members`   | `/RemoveGroupMembers`                      | Teams Update          |
| `get-user-acu-cap`       | `/GetUserAcuCap`                           | Teams de solo lectura |
| `update-user-acu-cap`    | `/UpdateUserAcuCap`                        | Teams Update          |

Al ejecutar el script sin especificar un comando (la invocación original), se ejecuta el informe de `usage`.

<div id="output-and-errors">
  ## Salida y errores
</div>

Todos los comandos imprimen JSON en stdout. Los resultados paginados (filas de usuarios de consumo de ACU, `list-groups`, `list-group-members`) se recuperan automáticamente hasta la última página y se combinan en una única respuesta. Los errores de la API se imprimen en stderr con el formato `code: message` y el script finaliza con el código de estado `1`.

<div id="examples">
  ## Ejemplos
</div>

<div id="per-user-usage-report">
  ### Informe de uso por usuario
</div>

```bash theme={null}
python windsurf_analytics.py \
    --service-key YOUR_SERVICE_KEY \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z \
    --end 2025-03-31T23:59:59Z
```

<div id="acu-consumption">
  ### Consumo de ACU
</div>

```bash theme={null}
# Total de ACU del equipo más filas por usuario del ciclo de facturación actual
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Desglose histórico por grupo (la ventana no puede abarcar más de 90 días),
# con filas por usuario para un grupo
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z --end 2025-03-31T23:59:59Z \
    --group-id GROUP_A_ID --group-user-rows GROUP_A_ID
```

Opciones de `acu-consumption`: `--current-cycle` o `--start`/`--end` seleccionan el período; `--include-team-total`, `--group-id` repetible (máx. 100) y las opciones mutuamente excluyentes `--team-user-rows` / `--group-user-rows GROUP_ID` seleccionan los datos; `--page-size` ajusta el tamaño de página por solicitud (se recuperan todas las páginas de todos modos). Se requiere al menos una opción de selección de datos. Una clave limitada a un grupo solo puede seleccionar el grupo que tiene asignado y no puede solicitar totales del equipo ni filas de usuarios del equipo.

<div id="group-management">
  ### Gestión de grupos
</div>

```bash theme={null}
# Listar grupos y consultar un grupo
python windsurf_analytics.py list-groups --api-url https://your-server.com
python windsurf_analytics.py get-group --api-url https://your-server.com \
    --group-id GROUP_ID

# Crear un grupo y configurar sus modelos y su límite de ACU
python windsurf_analytics.py create-group --api-url https://your-server.com \
    --name Engineering
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID \
    --cascade-models MODEL_UID_1,MODEL_UID_2 \
    --set-cycle-acu-limit 50

# Quitar la restricción de modelos o el límite de ACU de un grupo. La API del servicio
# exige un valor positivo al establecer el límite de un grupo; quitarlo es una operación aparte.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Gestionar la membresía (correos separados por comas, máx. 1000)
python windsurf_analytics.py add-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov,lead@agency.gov
python windsurf_analytics.py remove-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov

# Eliminar un grupo (idempotente)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID
```

<div id="user-acu-caps">
  ### Límites de ACU por usuario
</div>

```bash theme={null}
# Consulta el límite configurado y el efectivo de un usuario (selecciónalo con --email o --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Establece un límite (0 bloquea al usuario) o elimina la anulación
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --set-cycle-acu-limit 25
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --clear-cycle-acu-limit
```