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

# Python SDK

> Rufen Sie Analysen ab und verwalten Sie Gruppen und ACU-Obergrenzen über die Befehlszeile mit dem Python SDK.

<Info>
  Diese Dokumentation gilt für die Federal Deployments von Devin. [Zurück zur Devin-Dokumentation](/de/get-started/devin-intro)
</Info>

Das Python SDK (`windsurf_analytics.py`) ist ein Befehlszeilen-Client für die Endpunkte der [Federal API](/de/federal/api/overview): Nutzungsberichte, [ACU-Verbrauch](/de/federal/api/acu-consumption), [Gruppenverwaltung](/de/federal/api/group-management) und [ACU-Obergrenzen für Nutzer](/de/federal/api/acu-caps). Wenden Sie sich an Ihre Cognition-Ansprechperson, um das Skript für Ihr Deployment zu erhalten.

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

* Python 3
* Die Bibliothek `requests`: `pip install requests`

<div id="authentication">
  ## Authentifizierung
</div>

Jeder Befehl unterstützt die folgenden gemeinsamen Flags:

| Flag            | Beschreibung                                                                                                            |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--service-key` | Service-Schlüssel zur Authentifizierung. Kann auch über die Umgebungsvariable `WINDSURF_SERVICE_KEY` festgelegt werden. |
| `--api-url`     | Basis-URL des API-Servers Ihres Deployments (`https://<your-server>`). HTTPS ist erforderlich.                          |

Die Rolle des Service-Schlüssels muss über die für den jeweiligen Befehl erforderliche Berechtigung verfügen – siehe [Berechtigungstabelle](/de/federal/api/overview#required-permissions). Alle Analytics-Befehle erfordern außerdem eine Team-Ebene mit Zugriff auf die Analytics-API.

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

| Befehl                 | Endpunkt                                   | Erforderliche Berechtigung |
| ---------------------- | ------------------------------------------ | -------------------------- |
| `usage` (Standard)     | `/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               |

Wenn Sie das Skript ohne Befehl ausführen (der ursprüngliche Aufruf), wird der Bericht `usage` ausgeführt.

<div id="output-and-errors">
  ## Ausgabe und Fehler
</div>

Alle Befehle geben JSON auf stdout aus. Paginierte Ergebnisse (Nutzerzeilen zum ACU-Verbrauch, `list-groups`, `list-group-members`) werden automatisch bis zur letzten Seite abgerufen und zu einer einzigen Antwort zusammengeführt. API-Fehler werden als `code: message` auf stderr ausgegeben, und das Skript wird mit Status `1` beendet.

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

<div id="per-user-usage-report">
  ### Nutzungsbericht pro Nutzer
</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">
  ### ACU-Verbrauch
</div>

```bash theme={null}
# ACU-Gesamtwert des Teams sowie Zeilen pro Nutzer für den aktuellen Abrechnungszeitraum
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Historische Aufschlüsselung pro Gruppe (Zeitfenster darf maximal 90 Tage umfassen),
# mit Zeilen pro Nutzer für eine Gruppe
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
```

`acu-consumption`-Flags: `--current-cycle` oder `--start`/`--end` legen den Zeitraum fest; `--include-team-total`, wiederholbare `--group-id` (max. 100) und die sich gegenseitig ausschließenden Optionen `--team-user-rows` / `--group-user-rows GROUP_ID` legen die Daten fest; `--page-size` passt die Seitengröße pro Anfrage an (alle Seiten werden unabhängig davon abgerufen). Mindestens ein Flag zur Datenauswahl ist erforderlich. Ein auf eine Gruppe beschränkter Schlüssel kann nur die ihm zugewiesene Gruppe auswählen und weder Team-Gesamtwerte noch Team-Nutzerzeilen anfordern.

<div id="group-management">
  ### Gruppenverwaltung
</div>

```bash theme={null}
# Gruppen auflisten und eine einzelne Gruppe abrufen
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

# Gruppe erstellen sowie deren Modelle und ACU-Obergrenze konfigurieren
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

# Modellbeschränkung oder ACU-Obergrenze einer Gruppe aufheben. Die Service-API verlangt beim
# Setzen einer Gruppen-Obergrenze einen positiven Wert; das Aufheben ist ein separater Vorgang.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Mitgliedschaften verwalten (kommagetrennte E-Mail-Adressen, max. 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

# Gruppe löschen (idempotent)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID
```

<div id="user-acu-caps">
  ### ACU-Obergrenzen für Nutzer
</div>

```bash theme={null}
# Konfigurierte und effektive Obergrenze eines Nutzers abrufen (Auswahl über --email oder --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Obergrenze festlegen (0 sperrt den Nutzer) oder den Override entfernen
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
```