> ## 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.
# Verbrauch abrufen
> Analytics zum Credit- oder ACU-Verbrauch mit flexibler Filterung, Gruppierung und Paginierung abfragen.
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 Nutzungsüberwachung in Echtzeit gedacht. Die Daten werden stündlich aggregiert und das
Rate-Limit ist niedrig (10 Anfragen pro Stunde pro Team). Verwenden Sie ihn für regelmäßige Berichte und Bulk-Exporte.
## Authentifizierung
Dieser Endpunkt verwendet die Authentifizierung per **Bearer-Token**. Geben Sie Ihren Service-Schlüssel im `Authorization`-Header an:
```
Authorization: Bearer
```
Der Service-Schlüssel muss über die Berechtigung **Analytics Read** verfügen. Legen Sie in Ihren [Team Settings](https://windsurf.com/team/settings) unter "Service-Schlüssel" einen an.
## Abrechnungsstrategie
Die Antwortstruktur hängt von der Abrechnungsstrategie Ihres Teams ab:
| Strategie | Befüllte Felder | Beschreibung |
| --------- | -------------------------------- | ------------------------------------------------------ |
| `CREDITS` | `prompt_credits`, `flex_credits` | Standard-Teams in Enterprise SaaS |
| `ACU` | `billed_acus` | Teams, die nach Agent Compute Units abgerechnet werden |
Das Feld `message_count` (innerhalb von `consumption`) wird unabhängig von der Abrechnungsstrategie immer befüllt.
## 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 aggregierte Zeile für den gesamten Datumsbereich zurück
* **`granularity=daily`** — jede Zeile enthält einen `timestamp` im Format `YYYY-MM-DD`
* **`granularity=monthly`** — jede Zeile enthält einen `timestamp` im Format `YYYY-MM`
* **`group_by=user`** — jede Zeile enthält eine `user_id` und `user_email`
* **`group_by=user,model_uid`** — jede Zeile enthält `user_id`, `user_email` und `model_uid`
* **`group_by=ide`** — jede Zeile enthält ein `ide`
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 `page_cursor`-Abfrageparameter,
um die nächste Seite abzurufen.
Page-Cursor laufen nach 24 Stunden ab. Eine nachfolgende Seitenanfrage zählt nicht als neue Abfrage für Ihr Rate-Limit.
## 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.
## Anfragelimits
Dieser Endpunkt ist auf **10 Anfragen pro Stunde** pro Team begrenzt. Wenn dieses Limit überschritten wird, gibt der
Server `429 Too Many Requests` mit einem `Retry-After`-Header zurück.
Die Paginierung einer früheren Abfrage (über einen `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
periodische Berichte 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/consumption
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/consumption:
get:
summary: Verbrauchsanalysen abrufen
description: >
Fragen Sie Credit- oder ACU-Verbrauchsdaten für das authentifizierte
Team ab. Die Ergebnisse stammen aus stündlich aggregierten
Abrechnungsereignissen und können nach Datumsbereich, Produkt, Modell
und Gruppe gefiltert werden.
Die Form der Antwort hängt von der Abrechnungsstrategie des Teams ab:
- **Credit-basierte** Teams erhalten in jeder Zeile `prompt_credits` und
`flex_credits`.
- **ACU-basierte** Teams erhalten in jeder Zeile `billed_acus`.
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: getConsumption
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 Verbrauchsdaten 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, werden die Ergebnisse über den gesamten
Datumsbereich aggregiert.
- name: group_by
in: query
required: false
schema:
type: string
description: >
Kommagetrennte Liste von Dimensionen, nach denen die Ergebnisse
gruppiert werden. Unterstützte Dimensionen:
- `user` — enthält in jeder Zeile `user_id` und `user_email`
- `model_uid` — enthält in jeder Zeile `model_uid`
- `ide` — enthält in jeder Zeile `ide`
example: user,model_uid
- name: models
in: query
required: false
schema:
type: string
description: >-
Kommagetrennte Liste von Modell-UIDs, auf die die Ergebnisse
gefiltert werden sollen.
example: claude-4-sonnet,gpt-4.1
- name: group_id
in: query
required: false
schema:
type: string
description: >-
Filtert die Ergebnisse auf Nutzer in einer bestimmten Gruppe. Der
Service-Schlüssel muss Zugriff auf diese Gruppe haben.
- name: user_id
in: query
required: false
schema:
type: string
description: Filtert die Ergebnisse auf einen bestimmten Nutzer (Auth-UID).
- 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: Verbrauchsdaten erfolgreich zurückgegeben.
headers:
ETag:
schema:
type: string
description: >-
Entity-Tag zur Cache-Validierung. Übergeben Sie ihn in
nachfolgenden Anfragen als `If-None-Match`.
Cache-Control:
schema:
type: string
description: Cache-Direktive (z. B. `private, max-age=3600`).
content:
application/json:
schema:
$ref: '#/components/schemas/ConsumptionResponse'
examples:
credits:
summary: Credit-basiertes Team mit täglicher Granularität
value:
data:
- timestamp: '2026-01-15T00:00:00.000Z'
user_id: user_abc123
user_email: alice@example.com
consumption:
prompt_credits: 1250
flex_credits: 340
message_count: 87
- timestamp: '2026-01-15T00:00:00.000Z'
user_id: user_def456
user_email: bob@example.com
consumption:
prompt_credits: 980
flex_credits: 150
message_count: 52
pagination:
next_page_cursor: null
metadata:
billing_strategy: CREDITS
data_freshness: '2026-01-16T03:00:00.000Z'
query_time_ms: 1423
team_id: team_abc123
acu:
summary: ACU-basiertes Team
value:
data:
- consumption:
billed_acus: 42.75
message_count: 310
pagination:
next_page_cursor: null
metadata:
billing_strategy: ACU
data_freshness: '2026-01-16T03:00:00.000Z'
query_time_ms: 892
team_id: team_def456
'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
date_range:
value:
error: date range must not exceed 90 days
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 einem erneuten 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:
ConsumptionResponse:
type: object
required:
- data
- pagination
- metadata
properties:
data:
type: array
items:
$ref: '#/components/schemas/ConsumptionRow'
description: Array von Zeilen mit Verbrauchsdaten.
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:
billing_strategy:
type: string
enum:
- CREDITS
- ACU
description: >
Die Abrechnungsstrategie für das authentifizierte Team.
Bestimmt, welche Felder in `consumption` befüllt werden:
- `CREDITS` — `prompt_credits` und `flex_credits`
- `ACU` — `billed_acus`
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
bezogen wurde.
group_id:
type: string
description: >-
Die Gruppen-ID, auf die die Ergebnisse eingeschränkt wurden. Nur
vorhanden, wenn `group_id` übergeben wurde.
Error:
type: object
required:
- error
properties:
error:
type: string
description: Menschenlesbare Fehlermeldung.
ConsumptionRow:
type: object
required:
- consumption
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.
user_email:
type: string
description: >-
E-Mail-Adresse des Nutzers. Nur vorhanden, wenn `group_by` `user`
enthält.
examples:
- alice@example.com
model_uid:
type: string
description: Modellkennung. Nur vorhanden, wenn `group_by` `model_uid` enthält.
examples:
- claude-4-sonnet
ide:
type: string
description: IDE-Name. Nur vorhanden, wenn `group_by` `ide` enthält.
examples:
- windsurf
- jetbrains
consumption:
$ref: '#/components/schemas/Consumption'
Consumption:
type: object
description: >-
Nutzungsmetriken für die Zeile. Die Felder werden basierend auf der
Abrechnungsstrategie des Teams befüllt.
properties:
prompt_credits:
type: integer
format: int64
description: Verbrauchte Prompt-Credits (nur bei Credit-basierter Abrechnung).
flex_credits:
type: integer
format: int64
description: Verbrauchte Flex-Credits (nur bei Credit-basierter Abrechnung).
billed_acus:
type: number
format: double
description: Verbrauchte abgerechnete ACUs (nur bei ACU-basierter Abrechnung).
message_count:
type: integer
format: int64
description: >-
Anzahl der Nachrichten (Abrechnungsereignisse) in dieser Zeile. Wird
unabhängig von der Abrechnungsstrategie immer befüllt.
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“.
````