> ## 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 Python
> Consulte análises e gerencie grupos e limites de ACU pela linha de comando com o SDK Python.
Esta documentação se destina às implantações federais do Devin. [Voltar à documentação do Devin](/pt-BR/get-started/devin-intro)
O SDK Python (`windsurf_analytics.py`) é um cliente de linha de comando para os endpoints da [API federal](/pt-BR/federal/api/overview): relatórios de uso, [consumo de ACU](/pt-BR/federal/api/acu-consumption), [gerenciamento de grupos](/pt-BR/federal/api/group-management) e [limites de ACU por usuário](/pt-BR/federal/api/acu-caps). Entre em contato com seu representante da Cognition para obter o script da sua implantação.
## Requisitos
* Python 3
* Biblioteca `requests`: `pip install requests`
## Autenticação
Todos os comandos aceitam estas flags comuns:
| Flag | Descrição |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| `--service-key` | Chave de serviço para autenticação. Também pode ser definida pela variável de ambiente `WINDSURF_SERVICE_KEY`. |
| `--api-url` | URL base do servidor de API da sua implantação (`https://`). HTTPS é obrigatório. |
A função associada à chave de serviço deve ter a permissão exigida por cada comando — consulte a [tabela de permissões](/pt-BR/federal/api/overview#required-permissions). Todos os comandos de análises também exigem um nível de equipe com acesso à API de análises.
## Comandos
| Comando | Endpoint | Permissão necessária |
| ---------------------- | ------------------------------------------ | -------------------- |
| `usage` (padrão) | `/UserPageAnalytics` + `/CascadeAnalytics` | Teams Read-Only |
| `acu-consumption` | `/Analytics` | Analytics Read |
| `list-groups` | `/ListGroups` | Teams Read-Only |
| `get-group` | `/GetGroup` | Teams Read-Only |
| `create-group` | `/CreateGroup` | Teams Update |
| `update-group` | `/UpdateGroup` | Teams Update |
| `delete-group` | `/DeleteGroup` | Teams Update |
| `list-group-members` | `/ListGroupMembers` | Teams Read-Only |
| `add-group-members` | `/AddGroupMembers` | Teams Update |
| `remove-group-members` | `/RemoveGroupMembers` | Teams Update |
| `get-user-acu-cap` | `/GetUserAcuCap` | Teams Read-Only |
| `update-user-acu-cap` | `/UpdateUserAcuCap` | Teams Update |
A execução do script sem especificar um comando (a invocação original) gera o relatório de `usage`.
## Saída e erros
Todos os comandos imprimem JSON em stdout. Os resultados paginados (linhas de usuários de consumo de ACU, `list-groups`, `list-group-members`) são buscados automaticamente até a última página e mesclados em uma única resposta. Os erros da API são impressos em stderr no formato `code: message`, e o script é encerrado com o status `1`.
## Exemplos
### Relatório de uso por usuário
```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
```
### Consumo de ACUs
```bash theme={null}
# Total de ACU da equipe mais linhas por usuário do ciclo de faturamento atual
python windsurf_analytics.py acu-consumption \
--api-url https://your-server.com \
--current-cycle --include-team-total --team-user-rows
# Detalhamento histórico por grupo (o intervalo deve ser de no máximo 90 dias),
# com linhas por usuário de um 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
```
Flags de `acu-consumption`: `--current-cycle` ou `--start`/`--end` selecionam o período; `--include-team-total`, `--group-id` repetível (máx. 100) e `--team-user-rows` / `--group-user-rows GROUP_ID`, mutuamente exclusivos, selecionam os dados; `--page-size` ajusta o tamanho da página por requisição (todas as páginas são buscadas de qualquer forma). É necessário usar pelo menos uma flag de seleção de dados. Uma chave com escopo de grupo pode selecionar apenas o grupo a ela atribuído e não pode solicitar totais da equipe nem linhas de usuários da equipe.
### Gerenciamento de grupos
```bash theme={null}
# Listar grupos e consultar um 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
# Criar um grupo e configurar seus modelos e o limite 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
# Remover a restrição de modelos ou o limite de ACU de um grupo. A API do serviço exige um
# valor positivo ao definir o limite de um grupo; a remoção é uma operação à parte.
python windsurf_analytics.py update-group --api-url https://your-server.com \
--group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit
# Gerenciar associações (e-mails separados por vírgula, 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
# Excluir um grupo (idempotente)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
--group-id GROUP_ID
```
### Limites de ACU por usuário
```bash theme={null}
# Consultar o limite configurado e o limite efetivo de um usuário (selecione por --email ou --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
--email dev@agency.gov
# Definir um limite (0 bloqueia o usuário) ou remover o override
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
```