API usage analytics and request logs

Read API usage and request logs with a signed-in user's access JWT.

Authorization: Bearer <USER_ACCESS_JWT>

These endpoints show developer API-key traffic only. Website activity using a user JWT is excluded. Developer API keys cannot authenticate these requests.

Analytics

GEThttps://api.voicelab.uz/api/v1/account/analytics

Return aggregate VoiceLab API usage for the signed-in account.

Query parameters:

Parameter	Required	Rules
from	no	RFC3339 timestamp or YYYY-MM-DD; defaults to seven days ago
to	no	RFC3339 timestamp or YYYY-MM-DD; defaults to now; end date is exclusive
granularity	no	day (default) or hour; hourly windows are at most 31 days

The total window cannot be longer than 90 days. Times are interpreted and returned in UTC.

Example:

curl -fS 'https://api.voicelab.uz/api/v1/account/analytics?from=2026-08-01&to=2026-08-16&granularity=day' \
  -H "Authorization: Bearer $USER_ACCESS_JWT"

Response shape:

{
  "period": {
    "from": "2026-08-01T00:00:00Z",
    "to": "2026-08-16T00:00:00Z",
    "timezone": "UTC",
    "granularity": "day"
  },
  "summary": {
    "total_requests": 113,
    "successful_requests": 110,
    "failed_requests": 3,
    "success_rate": 0.973,
    "average_latency_ms": 289,
    "total_characters": 517,
    "total_duration_ms": 60000,
    "total_credits": 517,
    "billable_requests": 110,
    "total_cost_micros": 85000,
    "currency": "USD"
  },
  "series": [],
  "status_codes": [
    {"key":"200","value":110},
    {"key":"400","value":3}
  ],
  "top_routes": [
    {"key":"/v1/tts","value":80}
  ],
  "product_usage": [],
  "request_id": "req_01J..."
}

Allow unknown fields and new product entries in the analytics arrays.

Voice Isolator usage

Voice Isolator reports usage as voice_enhancer. Successful processing records usage against the submitting key and settles credits in one transaction. Failed jobs, polling and exports add no charges.

A 202 upload log means the job was accepted. Billing appears when processing completes.

Meeting AI usage

Meeting AI reports usage as meeting_ai. Successful processing records usage against the submitting key; a notes regeneration records a second usage event. Failed or deleted meetings and polling add no charges. A 202 upload log means the meeting was accepted.

LLM usage

LLM completions record settled usage with product llm and operation chat.completions. Token details and exact fractional credit units are available through the LLM request-status endpoint. A failed generation can still be billed when usage is known.

An HTTP 200 for an SSE stream does not prove successful completion or settlement. Retain X-LLM-Request-ID and inspect its status if the stream ends without [DONE]. Developer prompts, completions, reasoning, and tool contents are not saved in chat tables or request logs. Ask activity authenticated with a JWT remains separate from developer LLM usage.

Request logs

GEThttps://api.voicelab.uz/api/v1/account/request-logs

List individual developer API requests for troubleshooting.

Supported filters:

from=2026-08-01
to=2026-08-16
limit=50
cursor=<opaque cursor>
status=500
method=POST
route=/v1/tts
api_key_id=key_01J...

status and code are accepted as aliases. limit defaults to 50 and must be 1–100. Use next_cursor unchanged for the next request.

Example response:

{
  "items": [
    {
      "request_id": "req_01J...",
      "timestamp": "2026-08-16T12:00:00Z",
      "method": "POST",
      "route": "/v1/tts",
      "status_code": 200,
      "latency_ms": 289,
      "request_bytes": 120,
      "response_bytes": 184320,
      "api_key_id": "key_01J...",
      "api_key_prefix": "vlk_",
      "usage": {
        "product": "tts",
        "operation": "generate",
        "characters": 24,
        "duration_ms": 1180,
        "credits": 24,
        "billable": true
      }
    }
  ],
  "next_cursor": null,
  "period": {
    "from": "2026-08-01T00:00:00Z",
    "to": "2026-08-16T00:00:00Z",
    "timezone": "UTC",
    "granularity": "day"
  },
  "request_id": "req_01J..."
}

usage is optional. It can include ttfb_ms, cost_micros, and currency in addition to the fields shown above. The raw API key, authorization header, transcript, text body, audio bytes, and signed storage URL are never exposed in request logs.

Analytics errors

Status	Code	Meaning
400	invalid_analytics_window, invalid_pagination, invalid_cursor, invalid_filter	Correct the query parameters
401	session_expired	Refresh the dashboard user session
500	internal_error	Retry and keep request_id for support
503	analytics_unavailable	Analytics storage is temporarily unavailable