Usage
Retrieve account usage metrics, workspace usage series with credit breakdowns, and track desktop voice usage through the Talkturo API.
curl "https://api.talkturo.com/api/usage/current?accountId=7b3f4c2a-5d61-4e89-9a72-1c6f8b0d4e25" \
-H "Authorization: Bearer tk_live_example_9xmk7q2r"
const response = await fetch(
"https://api.talkturo.com/api/usage/current?accountId=7b3f4c2a-5d61-4e89-9a72-1c6f8b0d4e25",
{
headers: {
Authorization: "Bearer tk_live_example_9xmk7q2r"
}
}
);
const usage = await response.json();
console.log(usage.credit_info.credits_remaining);
{
"limits": {
"monthly_credits": 10000,
"daily_credits": 500,
"max_daily_credits": 750,
"minutes_per_month": 1200,
"parallel_calls": 10,
"max_ai_agents": 25
},
"usage": {
"minutes_used": 184.5,
"calls_made": 428,
"credits_used": 3160,
"credits_remaining": 6840,
"peak_parallel_calls": 4,
"ai_agents_created": 8,
"daily_credits_used": 126,
"credits_rolled_over": 320
},
"remaining": {
"credits": 6840,
"daily_credits": 374,
"minutes": 1015.5,
"parallel_calls": 6,
"ai_agents": 17
},
"percentages": {
"credits": 31.6,
"daily_credits": 25.2,
"minutes": 15.4,
"parallel_calls": 40,
"ai_agents": 32
},
"credit_info": {
"monthly_credits": 10000,
"daily_credits": 500,
"max_daily_credits": 750,
"credits_used": 3160,
"credits_remaining": 6840,
"credits_rolled_over": 320,
"daily_credits_used": 126,
"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.desktop" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "conn_8f31c2d7",
"durationSeconds": 94.6,
"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.desktop",
"Content-Type": "application/json"
},
body: JSON.stringify({
connectionId: "conn_8f31c2d7",
durationSeconds: 94.6,
provider: "deepgram",
model: "nova-3",
userEmail: "jane.chen@acme.test"
})
});
const result = await response.json();
console.log(result.success);
{
"success": true,
"data": {}
}
{
"success": false,
"error": "Invalid JSON body"
}
{
"success": false,
"error": "Usage logging failed"
}
curl "https://api.talkturo.com/api/accounts/7b3f4c2a-5d61-4e89-9a72-1c6f8b0d4e25/usage?from=2026-09-01T00%3A00%3A00Z&to=2026-09-12T23%3A59%3A59Z&granularity=day&page=1&pageSize=25" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.session"
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/7b3f4c2a-5d61-4e89-9a72-1c6f8b0d4e25/usage?${params}`,
{
headers: {
Authorization:
"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.session"
}
}
);
const usage = await response.json();
console.log(usage.totals.total_credits);
{
"granularity": "day",
"series": [
{
"day": "2026-09-01",
"period": "2026-09-01",
"call_count": 42,
"total_credits": 318.4,
"stt_credits": 46.2,
"llm_credits": 121.7,
"tts_credits": 58.5,
"talkturo_credits": 32,
"telephony_credits": 44,
"realtime_credits": 16
}
],
"daily": [
{
"day": "2026-09-01",
"call_count": 42,
"total_credits": 318.4,
"stt_credits": 46.2,
"llm_credits": 121.7,
"tts_credits": 58.5,
"talkturo_credits": 32,
"telephony_credits": 44,
"realtime_credits": 16
}
],
"totals": {
"call_count": 42,
"total_credits": 318.4,
"stt_credits": 46.2,
"llm_credits": 121.7,
"tts_credits": 58.5,
"talkturo_credits": 32,
"telephony_credits": 44,
"realtime_credits": 16
},
"assistants": [
{
"id": "2e8f7a1b-6c43-4d90-b821-5a7c9f0e3d16",
"name": "Scheduling assistant"
}
],
"rows": [
{
"id": "usage_01j8m3f7k2",
"call_id": "call_01j8m3d9q4",
"started_at": "2026-09-01T14:22:08Z",
"ended_at": "2026-09-01T14:27:41Z",
"assistant_id": "2e8f7a1b-6c43-4d90-b821-5a7c9f0e3d16",
"assistant_name": "Scheduling assistant",
"total_cost": 7.58,
"stt_cost": 1.1,
"llm_cost": 2.91,
"tts_cost": 1.34,
"talkturo_cost": 0.76,
"telephony_cost": 1.05,
"realtime_cost": 0.42
}
],
"page": 1,
"pageSize": 25,
"rowCount": 42
}
{
"error": "Date range cannot exceed 366 days"
}
{
"error": "Forbidden"
}
{
"error": "Internal server error"
}
curl "https://api.talkturo.com/api/desktop/usage" \
-X POST \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktop" \
-H "x-talkturo-account: 7b3f4c2a-5d61-4e89-9a72-1c6f8b0d4e25" \
-H "Content-Type: application/json" \
-d '{
"session_id": "desktop_session_6f2a91c8",
"duration_seconds": 180,
"kind": "ask"
}'
const response = await fetch("https://api.talkturo.com/api/desktop/usage", {
method: "POST",
headers: {
Authorization:
"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktop",
"x-talkturo-account": "7b3f4c2a-5d61-4e89-9a72-1c6f8b0d4e25",
"Content-Type": "application/json"
},
body: JSON.stringify({
session_id: "desktop_session_6f2a91c8",
duration_seconds: 180,
kind: "ask"
})
});
const result = await response.json();
if (result.ok) {
console.log(result.calls_remaining);
}
{
"ok": true,
"calls_this_month": 128,
"calls_remaining": 872
}
{
"ok": false,
"reason": "missing_session_id"
}
{
"ok": false,
"reason": "over_cap",
"upgrade_url": "/home",
"calls_this_month": 1000,
"calls_limit": 1000
}
{
"ok": false,
"reason": "session_not_found"
}
{
"ok": false,
"reason": "workspace_access_denied"
}
{
"ok": false,
"reason": "count_failed",
"error": "Unable to count usage"
}
Usage endpoints
Use the usage endpoints to retrieve current account limits, analyze workspace usage over time, record desktop voice usage, and enforce desktop call limits.
Authentication methods
GET /api/usage/current accepts a Talkturo API key, a Supabase bearer session token, or a cookie-based Supabase session.
Send a Talkturo API key in the Authorization header:
Authorization: Bearer tk_live_example_9xmk7q2r
The desktop endpoints accept a Supabase access token issued for the authenticated desktop user:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.desktop
Invalid, expired, or missing tokens return 401.
GET /api/accounts/{accountId}/usage requires a valid Supabase web session. The authenticated user must own the account or have an account membership.
Usage values are returned as numbers. Credit breakdowns distinguish speech-to-text, language model, text-to-speech, Talkturo, telephony, and realtime costs where the endpoint provides that detail.
Get current account usage
Retrieve the current limits, monthly usage, remaining capacity, usage percentages, and credit configuration for an account.
GET /api/usage/current?accountId=7b3f4c2a-5d61-4e89-9a72-1c6f8b0d4e25
Authentication
Authenticate with a Talkturo API key, Supabase bearer session token, or cookie-based Supabase session.
Query parameters
Account or workspace identifier.
Request
Response
Response fields
Account limits returned by the account limits service. The object includes configured monthly, daily, minutes, parallel call, and AI agent limits.
Current account usage, including minutes, calls, credits, peak parallel calls, AI agents, and rollover values.
Remaining credits, daily_credits, minutes, parallel_calls, and ai_agents.
Percentage usage for credits, daily credits, minutes, parallel calls, and AI agents.
Credit totals, usage, rollover values, and feature flags for credit rollover and usage-based AI.
Log desktop voice usage
Record a desktop voice usage event with the provider, model, duration, and optional connection metadata.
POST /api/usage/voice
Authentication
Authenticate with a desktop Supabase JWT.
Request body
All request fields are optional. The handler applies these defaults:
connectionId:nulldurationSeconds:0provider:deepgrammodel:nova-3userEmail:null
Connection identifier stored in the event metadata. The value may be null.
Voice duration in seconds. The value is rounded to a non-negative number before logging.
Speech provider name. Defaults to deepgram.
Speech model name. Defaults to nova-3.
Optional user email stored in the event metadata. The value may be null.
Request
Response
Indicates whether the request was processed successfully.
Empty object returned after the usage event is processed.
The endpoint logs the event with kind set to voice. Database insert errors are logged by the server and do not make an otherwise valid request fail.
Get workspace usage
Retrieve usage series, daily metrics, credit totals, assistant filters, and paginated call-level cost rows for an account.
GET /api/accounts/7b3f4c2a-5d61-4e89-9a72-1c6f8b0d4e25/usage
Authentication and authorization
Authenticate with a Supabase web session. The authenticated user must be the account owner or a member of the account.
Path parameters
Account or workspace identifier.
Query parameters
Start of the usage range in ISO 8601 date-time format.
End of the usage range in ISO 8601 date-time format. The date range cannot exceed 366 days.
UUID of an assistant. Filters the usage series and call rows to that assistant.
Page number. Defaults to 1. Values below 1 are set to 1.
Number of call rows per page. Defaults to 25 and is limited to 100.
Series grouping. Defaults to day. When set to week, the series values are grouped by UTC Monday. The daily values remain daily.
dayweekRequest
Response
Response fields
Grouping used for the series response. The value is day or week.
Usage metrics grouped by the requested granularity. Weekly periods start on Monday in UTC.
Daily usage metrics for the requested date range, regardless of the granularity value.
Aggregated call count and credit costs for the requested range.
Assistants available for filtering, with each assistant's id and name.
Paginated call-level usage records with timestamps, assistant information, and cost breakdowns.
Current page number.
Number of rows requested for each page after server-side clamping.
Total number of matching call-level usage rows.
Usage series fields
Each object in series and daily includes the following fields:
Time and volume
day, period, and call_count identify the reporting period and number of calls.
Credit breakdown
total_credits, stt_credits, llm_credits, tts_credits, talkturo_credits, telephony_credits, and realtime_credits report credit usage by category.
Check desktop call usage
Check whether a desktop session can make another call and retrieve the current monthly count.
POST /api/desktop/usage
Authentication
Authenticate with a desktop Supabase JWT.
Request headers
Optional account or workspace identifier. When provided, the authenticated user must own or belong to the account.
Request body
Desktop session identifier.
Optional session duration. The handler parses this value but does not use it to calculate the response.
Optional usage kind. The handler accepts listen or ask but does not use the value to calculate the response.
listenaskRequest
Response
Indicates whether the desktop session passed usage checks.
Number of calls made during the current month. Returned on successful checks and over-cap responses.
Number of calls remaining under the monthly limit. Unlimited plans return -1.
Machine-readable failure reason. Possible values include invalid_body, missing_session_id, session_not_found, workspace_access_denied, no_access, over_cap, lookup_failed, limits_failed, and count_failed.
Monthly call limit. Returned when the session is over its cap.
Path to the upgrade page for no_access and over_cap responses.
Treat reason: "over_cap" as a usage limit response, not an authentication failure. The endpoint returns HTTP 402 and includes the current count and monthly limit.
Error handling
Handle the HTTP status before reading endpoint-specific fields. The usage endpoints use these status categories:
400: Missing or invalid request parameters or JSON.401: Missing or invalid desktop authentication.402: Desktop monthly call cap exceeded.403: Authenticated user lacks workspace access.404: Account limits or desktop session not found.500: Server, database, or usage counting failure.