> ## 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.
# Aktive Nutzer abrufen
> Fragen Sie die Anzahl unterschiedlicher aktiver Nutzer für Ihr Team ab, mit optionaler zeitlicher Granularität und Gruppierung pro Nutzer.
Dies ist ein **v2-Endpunkt**, der Bearer-Token-Authentifizierung und Abfrageparameter verwendet, im Gegensatz zur v1 Analytics-API, die Service-Schlüssel im Request-Body verwendet. Siehe unten [Authentifizierung](#authentication).
Dieser Endpunkt ist **nicht** für die Überwachung der Nutzung in Echtzeit gedacht. Die Daten werden stündlich aggregiert und das
Ratenlimit ist niedrig (10 Anfragen pro Stunde pro Team). Verwenden Sie ihn für regelmäßige Berichte und Massenexporte.
## Authentifizierung
Dieser Endpunkt verwendet die **Bearer-Token**-Authentifizierung. Geben Sie Ihren Service-Schlüssel im `Authorization`-Header an:
```
Authorization: Bearer
```
Der Service-Schlüssel muss die Berechtigung **Analytics Read** haben. Erstellen Sie ihn in Ihren [Team Settings](https://windsurf.com/team/settings) unter "Service Keys".
## Was als aktiver Nutzer gilt
Ein Nutzer wird für ein bestimmtes Zeitintervall als **aktiv** gezählt, wenn darin ein Abrechnungsereignis auftritt. Das
`active_users`-Feld gibt die Anzahl der eindeutigen Nutzer an.
Die Anzahl aktiver Nutzer umfasst die Nutzung aus **sowohl der Devin CLI als auch Devin Desktop**. Ein Nutzer, der
in einem der beiden (oder in beiden) aktiv ist, wird gezählt, und pro Zeitintervall nur einmal.
## Gruppierung und Granularität
Verwenden Sie `granularity` und `group_by`, um die Struktur der zurückgegebenen Daten zu steuern:
* **Keine Granularität oder Gruppierung** — gibt eine einzelne Zeile mit der Gesamtzahl aktiver Nutzer für den gesamten Datumsbereich zurück
* **`granularity=daily`** — jede Zeile enthält einen `timestamp` im Format `YYYY-MM-DD` (täglich aktive Nutzer)
* **`granularity=monthly`** — jede Zeile enthält einen `timestamp` im Format `YYYY-MM` (monatlich aktive Nutzer)
* **`group_by=user`** — gibt eine Zeile pro aktivem Nutzer mit einer `user_id` zurück; `active_users` ist in jeder Zeile `1`
Im Gegensatz zu [Verbrauch abrufen](/de/desktop/accounts/api-reference/get-consumption) unterstützt der Endpunkt für aktive Nutzer
bei `group_by` nur `user`. Andere Dimensionen (`model_uid`, `ide`) sind hier nicht gültig.
Die Ergebnisse sind paginiert, mit einer Standardseitengröße von 1.000 Zeilen (max. 10.000). Wenn weitere Ergebnisse verfügbar sind,
enthält die Antwort im Objekt `pagination` einen `next_page_cursor`. Übergeben Sie ihn als query-Parameter `page_cursor`,
um die nächste Seite abzurufen.
Seiten-Cursor laufen nach 24 Stunden ab. Eine nachfolgende Seitenanfrage zählt nicht als neue Abfrage für Ihr Ratenlimit.
## Caching
Antworten enthalten einen `ETag`-Header. Um redundante Datenübertragungen zu vermeiden, senden Sie den `If-None-Match`-Header
mit dem vorherigen `ETag`-Wert — der Server gibt `304 Not Modified` zurück, wenn sich die Daten nicht geändert haben.
## Ratenlimits
Für diesen Endpunkt gilt ein Limit von **10 Anfragen pro Stunde** pro Team. Wenn Sie dieses Limit überschreiten, gibt der
Server `429 Too Many Requests` mit einem `Retry-After`-Header zurück.
Die Paginierung einer früheren Abfrage (durch Folgen eines `next_page_cursor`) wird **nicht** auf dieses Limit angerechnet —
nur die erste Abfrage für jeden Bericht. Das niedrige Limit spiegelt wider, dass dieser Endpunkt für
regelmäßige Berichterstattung gedacht ist, nicht für die Nutzungsüberwachung in Echtzeit.
## OpenAPI
````yaml de/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: >
Die Analytics-API v2 stellt Analysen zum Credit- und ACU-Verbrauch für
Enterprise-Teams bereit.
Die Daten stammen aus stündlich aggregierten Abrechnungsereignissen und
unterstützen flexible Filterung, Gruppierung
und cursorbasierte Paginierung.
servers:
- url: https://server.codeium.com
security:
- bearerAuth: []
paths:
/api/v2alpha/analytics/active-users:
get:
summary: Analysen zu aktiven Nutzern abrufen
description: >
Fragen Sie die Anzahl der eindeutigen aktiven Nutzer für das
authentifizierte Team ab. Ein Nutzer wird für ein Zeitintervall als
aktiv gezählt, wenn darin ein beliebiges Abrechnungsereignis für ihn
vorliegt. Die Ergebnisse stammen aus stündlich aggregierten
Abrechnungsereignissen und können nach Datumsbereich, Produkt, Modell
und Gruppe gefiltert werden.
Verwenden Sie `granularity`, um die Anzahl nach Tag oder Monat
aufzuschlüsseln, und `group_by=user`, um eine Zeile pro Nutzer
zurückzugeben (dabei ist `active_users` in jeder Zeile `1`).
Antworten werden für 1 Stunde zwischengespeichert. Verwenden Sie
`If-None-Match` mit einem zuvor zurückgegebenen `ETag`, um ein `304 Not
Modified` zu erhalten, wenn sich die Daten nicht geändert haben.
Diese Endpunkte sind für regelmäßige Berichte und Massenexporte
ausgelegt. Sie sind **nicht** für die Echtzeit-Überwachung der Nutzung
gedacht: Die Daten werden stündlich aggregiert, und das Ratenlimit ist
niedrig (10 Anfragen pro Stunde pro Team).
operationId: getActiveUsers
parameters:
- name: start_date
in: query
required: true
schema:
type: string
format: date
description: Beginn des Datumsbereichs (einschließlich) im Format `YYYY-MM-DD`.
example: '2026-01-01T00:00:00.000Z'
- name: end_date
in: query
required: true
schema:
type: string
format: date
description: >-
Ende des Datumsbereichs (einschließlich) im Format `YYYY-MM-DD`. Der
Bereich darf 90 Tage nicht überschreiten.
example: '2026-01-31T00:00:00.000Z'
- name: product
in: query
required: true
schema:
type: string
enum:
- agent
description: Produkt, für das aktive Nutzer abgefragt werden sollen.
example: agent
- name: granularity
in: query
required: false
schema:
type: string
enum:
- daily
- monthly
description: >
Zeitgranularität für die Gruppierung der Ergebnisse. Wenn angegeben,
enthält jede Zeile ein Feld `timestamp`.
Wenn nicht angegeben, wird die Anzahl aktiver Nutzer über den
gesamten Datumsbereich aggregiert.
- name: group_by
in: query
required: false
schema:
type: string
enum:
- user
description: >
Dimension, nach der Ergebnisse gruppiert werden. Der Endpunkt für
aktive Nutzer unterstützt nur `user`; dabei wird
pro aktivem Nutzer eine Zeile zurückgegeben (jeweils mit
`active_users` = `1`).
example: user
- name: models
in: query
required: false
schema:
type: string
description: >-
Kommagetrennte Liste von Modell-UIDs, auf die Ergebnisse gefiltert
werden sollen.
example: claude-4-sonnet,gpt-4.1
- name: group_id
in: query
required: false
schema:
type: string
description: >-
Ergebnisse auf Nutzer in einer bestimmten Gruppe filtern. Der
Service-Schlüssel muss Zugriff auf diese Gruppe haben.
- name: user_id
in: query
required: false
schema:
type: string
description: Ergebnisse auf einen bestimmten Nutzer (Auth-UID) filtern.
- name: page_size
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 1000
description: Maximale Anzahl von Zeilen, die pro Seite zurückgegeben werden.
- name: page_cursor
in: query
required: false
schema:
type: string
description: >-
Opaker Cursor aus `pagination.next_page_cursor` einer vorherigen
Antwort, um die nächste Seite abzurufen.
- name: If-None-Match
in: header
required: false
schema:
type: string
description: >-
ETag-Wert aus einer vorherigen Antwort. Wenn sich die Daten nicht
geändert haben, gibt der Server `304 Not Modified` zurück.
responses:
'200':
description: Daten zu aktiven Nutzern erfolgreich zurückgegeben.
headers:
ETag:
schema:
type: string
description: >-
Entity-Tag zur Cache-Validierung. Dies in nachfolgenden Anfragen
als `If-None-Match` übergeben.
Cache-Control:
schema:
type: string
description: Cache-Direktive (z. B. `private, max-age=3600`).
content:
application/json:
schema:
$ref: '#/components/schemas/ActiveUsersResponse'
examples:
aggregate:
summary: Aktive Nutzer insgesamt im Datumsbereich
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: Täglich aktive Nutzer
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: Nach Nutzer gruppiert
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: >-
Die Daten haben sich seit dem in `If-None-Match` angegebenen ETag
nicht geändert.
'400':
description: Ungültige Anfrageparameter.
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: Authentifizierung fehlgeschlagen oder unzureichende Berechtigungen.
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: >-
Der angegebene Seiten-Cursor gehört nicht zum authentifizierten Team
oder zur angeforderten Gruppe.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
cursor_team_mismatch:
value:
error: page cursor does not belong to this team
'405':
description: HTTP-Methode nicht zulässig (nur `GET` wird unterstützt).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: >-
Ratenlimit überschritten (10 Anfragen pro Stunde pro Team). Die
Paginierung einer früheren Abfrage wird nicht auf dieses Limit
angerechnet.
headers:
Retry-After:
schema:
type: string
description: Empfohlene Wartezeit vor dem nächsten Versuch.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limited:
value:
error: rate limit exceeded
'503':
description: >-
Der Analytics-Dienst ist nicht verfügbar (z. B. in
self-hosted-Deployments).
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 von Datenzeilen zu aktiven Nutzern.
pagination:
type: object
properties:
next_page_cursor:
type:
- string
- 'null'
description: >
Opaker Cursor zum Abrufen der nächsten Ergebnisseite. Übergeben
Sie diesen Wert als Query-Parameter `page_cursor`
in einer Folgeanfrage. `null`, wenn keine weiteren Seiten
vorhanden sind.
Seiten-Cursor laufen nach 24 Stunden ab.
metadata:
type: object
properties:
data_freshness:
type: string
format: date-time
description: >-
Zeitstempel, der angibt, wann die zugrunde liegenden Daten
zuletzt aktualisiert wurden (auf die Stunde gekürzt).
query_time_ms:
type: integer
format: int64
description: Serverseitige Ausführungszeit der Abfrage in Millisekunden.
team_id:
type: string
description: >-
Die Team-ID, die aus dem authentifizierten Service-Schlüssel
ermittelt wurde.
group_id:
type: string
description: >-
Die Gruppen-ID, auf die die Ergebnisse beschränkt wurden. Nur
vorhanden, wenn `group_id` angegeben wurde.
Error:
type: object
required:
- error
properties:
error:
type: string
description: Menschenlesbare Fehlermeldung.
ActiveUsersRow:
type: object
required:
- active_users
properties:
timestamp:
type: string
description: >
Zeitfenster für die Zeile. Das Format hängt von `granularity` ab:
`YYYY-MM-DD` für täglich, `YYYY-MM` für monatlich.
Nur vorhanden, wenn `granularity` angegeben ist.
examples:
- '2026-05-01T00:00:00.000Z'
- 2026-05
user_id:
type: string
description: >-
Nutzerkennung (auth UID). Nur vorhanden, wenn `group_by` `user`
enthält.
active_users:
type: integer
format: int64
description: >
Anzahl unterschiedlicher aktiver Nutzer in der Zeile. Ein Nutzer
wird für ein Zeitfenster als aktiv gezählt, wenn
für ihn darin mindestens ein Abrechnungsereignis vorliegt. Bei
Gruppierung nach `user` ist dies immer `1`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
Ein Service-Schlüssel mit der Berechtigung **Analytics Read**, übergeben
als Bearer-Token im Header `Authorization`.
Erstellen Sie einen Service-Schlüssel in Ihren [Team
Settings](https://windsurf.com/team/settings) im Abschnitt „Service
Keys“.
````