Nutzung
Aktuelle Kontolimits und Nutzungsmetriken abrufen, Workspace-Nutzungszeitreihen mit Guthabenaufschlüsselungen analysieren und Desktop-Sprachnutzung über die Talkturo API verfolgen.
curl "https://api.talkturo.com/api/usage/current?accountId=acc_7f3a9c2d" \
-H "Authorization: Bearer tk_live_example_9xmk7q2r"
const response = await fetch(
"https://api.talkturo.com/api/usage/current?accountId=acc_7f3a9c2d",
{
headers: {
Authorization: "Bearer tk_live_example_9xmk7q2r",
},
},
);
const usage = await response.json();
console.log(usage);
{
"limits": {
"monthly_credits": 10000,
"daily_credits": 500,
"max_daily_credits": 500,
"minutes_per_month": 1000,
"parallel_calls": 10,
"max_ai_agents": 25
},
"usage": {
"minutes_used": 142.5,
"calls_made": 318,
"credits_used": 1840,
"peak_parallel_calls": 4,
"ai_agents_created": 8,
"credits_remaining": 8160
},
"remaining": {
"credits": 8160,
"daily_credits": 420,
"minutes": 857.5,
"parallel_calls": 6,
"ai_agents": 17
},
"percentages": {
"credits": 18.4,
"daily_credits": 16,
"minutes": 14.25,
"parallel_calls": 40,
"ai_agents": 32
},
"credit_info": {
"monthly_credits": 10000,
"daily_credits": 500,
"max_daily_credits": 500,
"credits_used": 1840,
"credits_remaining": 8160,
"credits_rolled_over": 250,
"daily_credits_used": 80,
"credit_rollover_enabled": true,
"usage_based_ai_enabled": false
}
}
{
"error": "accountId is required"
}
{
"error": "Account limits not found"
}
{
"error": "Failed to fetch usage data"
}
curl "https://api.talkturo.com/api/usage/voice" \
-X POST \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "conn_8d4f1a2c",
"durationSeconds": 185,
"provider": "deepgram",
"model": "nova-3",
"userEmail": "jane.chen@acme.test"
}'
const response = await fetch("https://api.talkturo.com/api/usage/voice", {
method: "POST",
headers: {
Authorization:
"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example",
"Content-Type": "application/json",
},
body: JSON.stringify({
connectionId: "conn_8d4f1a2c",
durationSeconds: 185,
provider: "deepgram",
model: "nova-3",
userEmail: "jane.chen@acme.test",
}),
});
const result = await response.json();
console.log(result);
{
"success": true,
"data": {}
}
{
"success": false,
"error": "Invalid JSON body"
}
{
"success": false,
"error": "Usage logging failed"
}
curl "https://api.talkturo.com/api/accounts/7b3a9c2d-1e4f-4a6b-8c2d-9f0e1a2b3c4d/usage?from=2026-09-01T00%3A00%3A00Z&to=2026-09-12T23%3A59%3A59Z&granularity=day&page=1&pageSize=25" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"
const accountId = "7b3a9c2d-1e4f-4a6b-8c2d-9f0e1a2b3c4d";
const params = new URLSearchParams({
from: "2026-09-01T00:00:00Z",
to: "2026-09-12T23:59:59Z",
granularity: "day",
page: "1",
pageSize: "25",
});
const response = await fetch(
`https://api.talkturo.com/api/accounts/${accountId}/usage?${params}`,
{
headers: {
Authorization:
"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example",
},
},
);
const usage = await response.json();
console.log(usage);
{
"granularity": "day",
"series": [
{
"day": "2026-09-01",
"period": "2026-09-01",
"call_count": 24,
"total_credits": 142.75,
"stt_credits": 18.4,
"llm_credits": 62.1,
"tts_credits": 31.25,
"talkturo_credits": 12,
"telephony_credits": 14,
"realtime_credits": 5
}
],
"daily": [
{
"day": "2026-09-01",
"call_count": 24,
"total_credits": 142.75,
"stt_credits": 18.4,
"llm_credits": 62.1,
"tts_credits": 31.25,
"talkturo_credits": 12,
"telephony_credits": 14,
"realtime_credits": 5
}
],
"totals": {
"call_count": 24,
"total_credits": 142.75,
"stt_credits": 18.4,
"llm_credits": 62.1,
"tts_credits": 31.25,
"talkturo_credits": 12,
"telephony_credits": 14,
"realtime_credits": 5
},
"assistants": [
{
"id": "a1b2c3d4-e5f6-4789-abcd-1234567890ef",
"name": "Terminassistent"
}
],
"rows": [
{
"id": "usage_8d4f1a2c",
"call_id": "call_3c7e9b1a",
"started_at": "2026-09-01T10:15:00Z",
"ended_at": "2026-09-01T10:18:42Z",
"assistant_id": "a1b2c3d4-e5f6-4789-abcd-1234567890ef",
"assistant_name": "Terminassistent",
"total_cost": 5.95,
"stt_cost": 0.77,
"llm_cost": 2.59,
"tts_cost": 1.3,
"talkturo_cost": 0.5,
"telephony_cost": 0.58,
"realtime_cost": 0.21
}
],
"page": 1,
"pageSize": 25,
"rowCount": 1
}
{
"error": "Date range cannot exceed 366 days"
}
{
"error": "Forbidden"
}
curl "https://api.talkturo.com/api/desktop/usage" \
-X POST \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
-H "Content-Type: application/json" \
-H "x-talkturo-account: 7b3a9c2d-1e4f-4a6b-8c2d-9f0e1a2b3c4d" \
-d '{
"session_id": "session_5f8a2c1d",
"duration_seconds": 120,
"kind": "listen"
}'
const response = await fetch("https://api.talkturo.com/api/desktop/usage", {
method: "POST",
headers: {
Authorization:
"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example",
"Content-Type": "application/json",
"x-talkturo-account": "7b3a9c2d-1e4f-4a6b-8c2d-9f0e1a2b3c4d",
},
body: JSON.stringify({
session_id: "session_5f8a2c1d",
duration_seconds: 120,
kind: "listen",
}),
});
const usage = await response.json();
console.log(usage);
{
"ok": true,
"calls_this_month": 18,
"calls_remaining": 82
}
{
"ok": true,
"calls_this_month": 0,
"calls_remaining": -1
}
{
"ok": false,
"reason": "over_cap",
"upgrade_url": "/home",
"calls_this_month": 100,
"calls_limit": 100
}
{
"ok": false,
"reason": "session_not_found"
}
Nutzungsdaten über die API abrufen
Rufen Sie Kontolimits, aktuelle Guthaben, Nutzungszeitreihen und Desktop-Sprachnutzung über die Talkturo API ab.
Senden Sie alle API-Anfragen an https://api.talkturo.com/api.
Authentifizierung
Die Nutzungsendpunkte verwenden zwei Authentifizierungsmethoden:
Verwenden Sie diese Authentifizierung für GET /api/usage/current. Senden Sie entweder einen Talkturo API-Key oder ein Supabase-Session-Token als Bearer-Token. Eine Cookie-basierte Supabase-Session wird ebenfalls akzeptiert.
Authorization: Bearer tk_live_example_9xmk7q2r
Verwenden Sie diese Authentifizierung für die Desktop-Endpunkte. Senden Sie ein gültiges Supabase-Access-Token als Bearer-Token.
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example
Aktuelle Kontonutzung abrufen
GET /api/usage/current?accountId=acc_7f3a9c2d
Dieser Endpunkt gibt die Limits, die Nutzung des aktuellen Monats, verbleibende Ressourcen und prozentuale Auslastungen eines Kontos zurück.
Anfrage
Konto- oder Workspace-Kennung, für die die Limits und Nutzungsdaten abgerufen werden.
Antwort
Antwortfelder
Kontolimits aus der Kontokonfiguration. Das Objekt enthält unter anderem monthly_credits, daily_credits, max_daily_credits, minutes_per_month, parallel_calls und max_ai_agents.
Nutzung des aktuellen Monats. Das Objekt enthält unter anderem minutes_used, calls_made, credits_used, peak_parallel_calls, ai_agents_created und credits_remaining.
Verbleibende Ressourcen für credits, daily_credits, minutes, parallel_calls und ai_agents.
Prozentuale Auslastung für credits, daily_credits, minutes, parallel_calls und ai_agents.
Zusammengefasste Guthabeninformationen einschließlich verbrauchter, verbleibender und übertragener Guthaben.
accountId ist erforderlich. Der Handler prüft im Pfad ohne zusätzliche Kontoanforderung nicht unabhängig, ob die angegebene Kontokennung zum authentifizierten Benutzer gehört. Verwenden Sie nur Kontokennungen, auf die der authentifizierte Aufrufer zugreifen darf.
Desktop-Sprachnutzung protokollieren
POST /api/usage/voice
Verwenden Sie diesen Endpunkt, um ein Desktop-Sprachnutzungsereignis zu protokollieren. Die Authentifizierung erfolgt über ein Desktop-JWT.
Anfrage
Kennung der Desktop-Verbindung. Der Standardwert ist null.
Dauer der Sprachnutzung in Sekunden. Der Wert wird auf eine nicht negative Ganzzahl gerundet. Der Standardwert ist 0.
Name des Sprachdienstanbieters. Der Standardwert ist deepgram.
Name des verwendeten Sprachmodells. Der Standardwert ist nova-3.
E-Mail-Adresse des Desktop-Benutzers. Der Standardwert ist null.
Antwort
Gibt an, ob die Anfrage verarbeitet wurde.
Leeres Objekt bei erfolgreicher Verarbeitung.
Ein Fehler beim Einfügen des Nutzungsereignisses wird protokolliert, führt aber nicht automatisch zu einem Fehler der Anfrage. Der berechnete Kostenwert basiert auf durationSeconds / 60 * 0.0077.
Workspace-Nutzung für einen Zeitraum abrufen
GET /api/accounts/{accountId}/usage
Dieser Endpunkt liefert eine tägliche oder wöchentliche Nutzungszeitreihe, aggregierte Summen und paginierte Anrufdaten für einen Workspace. Sie benötigen eine gültige Web-Supabase-Session. Der authentifizierte Benutzer muss Eigentümer des Kontos sein oder über eine Mitgliedschaft verfügen.
Anfrage
Kennung des Workspace oder Kontos.
Startzeitpunkt des Nutzungszeitraums im ISO-8601-Format.
Endzeitpunkt des Nutzungszeitraums im ISO-8601-Format.
UUID eines Assistenten. Wenn Sie den Parameter angeben, werden Nutzungs- und Anrufdaten auf diesen Assistenten begrenzt.
Seitennummer der Anrufdaten. Der Standardwert ist 1. Werte kleiner als 1 werden auf 1 gesetzt.
Anzahl der Anrufdaten pro Seite. Der Standardwert ist 25. Der Wert wird auf den Bereich von 1 bis 100 begrenzt.
Granularität der series. Der Standardwert ist day. Nur der exakte Wert week erzeugt eine wöchentliche Gruppierung. Andere Werte werden als day behandelt.
dayweekAntwort
Antwortfelder
Verwendete Granularität der series: day oder week.
Aggregierte Nutzungsdaten nach der angeforderten Granularität. Bei week beginnt jede Periode an einem Montag in UTC.
Tägliche Nutzungsdaten unabhängig von der angeforderten Granularität.
Summen für call_count, total_credits, stt_credits, llm_credits, tts_credits, talkturo_credits, telephony_credits und realtime_credits.
Assistenten, die im angeforderten Workspace verfügbar sind.
Paginierte Liste einzelner Anruf- und Kostenaufzeichnungen.
Aktuelle Seitennummer.
Angewendete Seitengröße nach der Begrenzung auf 1 bis 100.
Anzahl der verfügbaren Aufzeichnungen im angeforderten Zeitraum.
from und to sind erforderlich und dürfen höchstens 366 Tage auseinanderliegen. Der authentifizierte Benutzer muss für den angegebenen Workspace berechtigt sein.
Desktop-Nutzung prüfen und erfassen
POST /api/desktop/usage
Verwenden Sie diesen Endpunkt, um zu prüfen, ob eine Desktop-Sitzung Zugriff hat und wie viele Aufrufe im aktuellen Monat bereits gezählt wurden.
Anfrage
Optionale Workspace- oder Kontokennung. Wenn Sie den Header angeben, muss der authentifizierte Benutzer Eigentümer oder Mitglied des Kontos sein.
Kennung der Desktop-Sitzung. Der Endpunkt prüft, ob die Sitzung existiert und zum authentifizierten Benutzer gehört.
Optionale Sitzungsdauer in Sekunden. Der aktuelle Handler liest den Wert, verwendet ihn aber nicht für die Nutzungsprüfung.
Optionale Nutzungsart. Der aktuelle Handler liest den Wert, verwendet ihn aber nicht für die Nutzungsprüfung.
listenaskAntwort
Gibt an, ob der Desktop-Aufruf autorisiert und innerhalb des Nutzungslimits liegt.
Anzahl der Aufrufe im aktuellen Monat.
Verbleibende Aufrufe. Bei unbegrenzten Tarifen ist der Wert -1.
Fehlergrund, zum Beispiel invalid_body, missing_session_id, session_not_found, no_access oder over_cap.
Pfad zur Upgrade-Seite bei fehlendem Desktop-Zugriff oder überschrittenem Nutzungslimit.
Der Endpunkt akzeptiert auch OPTIONS ohne Authentifizierung. Diese Anfrage dient der Desktop-CORS-Unterstützung und prüft keine Sitzung.