Abrufen der Organisations-Punktverbrauchsverteilung

Abrufen des Anteils und der Rangliste der Organisationspunkte oder Tokens nach Agent / Workflow sowie der Trends nach Tag, Woche und Monat. Es ist möglich, nur Agenten oder nur Workflows anzuzeigen.

Hinweis: Maximal 92 Tage Daten abrufbar; es werden nur Entwicklungsbereiche gezählt, der Abdeckungsbereich siehe unten unter „Statistik-Definition“.

Anforderungsmodus

GET

Aufrufadresse

https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution

Authentifizierung beim Aufruf

Verwendung der Kontostufen DevKey / DevSecret für die Basic-Authentifizierung: Authorization: Basic ${BASIC_TOKEN}, wobei ${BASIC_TOKEN} die Base64-Codierung von DevKey:DevSecret ist.

Das aufrufende Konto muss Mitglied der Organisation sein, die org_id entspricht, und über die Berechtigung „Nutzungsstatistik ansehen“ verfügen (Organisationseigentümer und Administratoren haben diese Berechtigung standardmäßig).
Bitte verwenden Sie die Adresse des Rechenzentrums, in dem sich die Organisation befindet. ${endpoint} wird aus der Abfrage der Organisationsliste übernommen: region (SG → sg, TH → th, JP → jp). Verwenden Sie eine andere Datenzentrum-Adresse, erhalten Sie die Meldung „Nicht Mitglied dieser Organisation“.

Aufrufhäufigkeit

Jeder Entwickler-Schlüssel darf diesen Endpunkt höchstens 10 Mal pro Minute aufrufen.
Jeder Aufruf wird gleichzeitig auf das organisationsweite Kontingent „Statistik-API“ pro Minute angerechnet und teilt dieses Kontingent mit dem Agent-API-Schlüssel für Statistikendpunkte.
Die Abfrageergebnisse werden 10 Minuten zwischengespeichert, es wird empfohlen, einmal täglich abzurufen.

Anfrage

Beispielanfrage

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \ -H 'Authorization: Basic ${BASIC_TOKEN}'

                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'

Dieser Codeblock im schwebenden Fenster

Anfrage-Header

Feld	Typ	Beschreibung
Authorization	Basic ${BASIC_TOKEN}	Verwenden Sie ein Basic Token, das nach `DevKey:DevSecret` Base64 kodiert ist.

Anfrage-Parameter

Feld	Typ	Erforderlich	Beschreibung
org_id	String	Ja	Organisations-ID.
start_time	Long	Ja	Startzeit, Millisekunden-Zeitstempel. Nach der Zeitzone der Organisation bis 0 Uhr des Tages erweitert.
end_time	Long	Ja	Endzeit (exklusiv), Millisekunden-Zeitstempel. Der Zeitraum darf maximal 92 Tage umfassen.
metric	String	Nein	`CREDITS` (Credits, Standard) oder `TOKENS`.
granularity	String	Nein	Zeitliche Granularität des Trends: `DAY` (Standard), `WEEK` (ab Montag), `MONTH`.
agent_type	String	Nein	`AGENT` nur Agent ansehen, `WORKFLOW` nur Workflow ansehen; wenn nicht übermittelt, werden beide Typen zusammen bewertet.
top_n	Integer	Nein	Anzahl der Einträge in der Trendserie, 1 bis 50, Standard 50, die übrigen werden in einer Zeile `OTHER` zusammengeführt.

Antwort

Antwortbeispiel

{ "code": 0, "message": "OK", "data": { "timezone": "+07:00", "data_since": "2026-10-15", "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"], "total": 812.4411, "series": [ { "row_type": "ITEM", "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "total": 402.1200, "share": 49.49, "points": [130.5000, 141.0200, 130.6000] }, { "row_type": "OTHER", "agent_id": null, "name": null, "agent_type": null, "total": 410.3211, "share": 50.51, "points": [120.1000, 150.2000, 140.0211] } ], "ranking": [ { "row_type": "ITEM", "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "total": 402.1200, "share": 49.49 } ] } }

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "timezone": "+07:00",
        "data_since": "2026-10-15",
        "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"],
        "total": 812.4411,
        "series": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49,
                "points": [130.5000, 141.0200, 130.6000]
            },
            {
                "row_type": "OTHER",
                "agent_id": null,
                "name": null,
                "agent_type": null,
                "total": 410.3211,
                "share": 50.51,
                "points": [120.1000, 150.2000, 140.0211]
            }
        ],
        "ranking": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49
            }
        ]
    }
}

Dieser Codeblock im schwebenden Fenster

Erfolgreiche Antwort

Feld	Typ	Beschreibung
timezone	String	Zeitzone der Organisation (UTC-Verschiebung, z. B. `+07:00`).
data_since	String	Das früheste Datum, ab dem Credits-Daten verfügbar sind (`yyyy-MM-dd`); Zeiträume davor sind unvollständig; wenn noch keine Daten vorhanden sind, dann `null`.
buckets	String[]	Startdatum der Zeitfenster in aufsteigender Reihenfolge: tagesweise für den Tag, wöchentlich ab Montag (`yyyy-MM-dd`), monatlich ab `yyyy-MM`. `points` entspricht dieser Reihenfolge.
total	Number	Gesamtsumme im Zeitraum (Credits oder Token, abhängig von `metric`).
series	Object[]	Top `top_n` Reihen für Trenddarstellung, nach Gesamtmenge absteigend; der Rest wird in einer Zeile zusammengefasst `row_type = OTHER`.
ranking	Object[]	Vollständiges Ranking, maximal 500 Zeilen; darüber hinaus zusammengefasst in einer Zeile `OTHER`. `points` nicht enthalten.
series[].row_type / ranking[].row_type	String	`ITEM` ein Agent oder Workflow; `OTHER` zusammengefasster Eintrag; `UNATTRIBUTED` Verbrauch, der keinem Agenten zugeordnet ist (z. B. Wissensspeicher, Spracherkennung); falls `agent_type` übermittelt wird, wird diese Zeile nicht zurückgegeben.
series[].agent_id / ranking[].agent_id	String	ID des Agenten oder Workflows; `OTHER` / `UNATTRIBUTED` Zeilen als `null`.
series[].name / ranking[].name	String	Name; `OTHER` / `UNATTRIBUTED` Zeilen als `null`.
series[].agent_type / ranking[].agent_type	String	`AGENT` oder `WORKFLOW`; `OTHER` / `UNATTRIBUTED` Verhalten `null`.
series[].total / ranking[].total	Number	Gesamtsumme des Intervalls, auf 4 Dezimalstellen gerundet.
series[].share / ranking[].share	Number	Prozentsatz der Gesamtsumme des Intervalls, von 0 bis 100, auf 2 Dezimalstellen gerundet.
series[].points	Number[]	Werte für jeden Zeitbereich.

Fehlerantwort

Feld	Typ	Beschreibung
code	Integer	Fehlercode.
message	String	Fehlerdetails.

Fehlercodes

Die HTTP-Statuscodes entsprechen den ersten drei Ziffern des Fehlercodes, z. B. entspricht 40000 dem Code 400, 40100 dem Code 401, 403132 dem Code 403.

Fehlercode	Beschreibung
40000	Parameterfehler, z. B. fehlender Pflichtparameter oder ungültiger Parameterwert.
40001	Zu häufige Anfragen: Dieser Entwicklerschlüssel hat das Minutenlimit dieser Schnittstelle überschritten.
40008	Überschreitung des Minutenlimits für „Statistik-APIs“ im Organisationspaket.
40010	Schnittstelle vorübergehend geschlossen, bitte später erneut versuchen.
40100	Keine Berechtigung: Fehlende Nutzungsansicht-Berechtigung.
40105	Kein Mitglied dieser Organisation oder Aufruf einer Adresse eines anderen Datenzentrums.
40324	DevKey oder DevSecret fehlerhaft.
403132	Ungültiger Zeitraum: Startzeit nicht früher als Endzeit oder Überschreitung des maximalen Abfragebereichs.

Statistikdefinition

Statistikbereich: Nur der Entwicklungsbereich wird erfasst, einschließlich API, Freigabeseiten, Webeinbettungen, Bubble-Komponenten, LiveDesk sowie aller Instant-Messaging- und Telefonkanäle und der Workflows im Entwicklungsbereich; die Nutzung des Arbeitsbereichs (GWork) wird nicht erfasst, ebenso wenig wie der bereits veröffentlichte Agent, der im Arbeitsbereich verwendet wird. Daher kann der Gesamtbetrag leicht niedriger sein als der gleiche Zeitraum auf der Konsole unter „Organisation → Nutzung“.
Credits: Alle Verbrauchstypen (ohne Punkteverfall und Abonnementzahlungen); der Verbrauch von Workflows wird unter dem eigenen Workflow verbucht.
Datenstartpunkt: Ab dem Datum der Einführung der Funktion (data_since), kein Nachtragen historischer Daten.
Aktualisierungsfrequenz: Aktualisierung in Echtzeit.