Usage

Usage endpoints provide essential metrics and statistics about your organization's resource consumption across all replicas. These endpoints help you monitor conversation volumes, knowledge base utilization, and track usage patterns for billing, capacity planning, and optimization purposes.

All usage endpoints return aggregated data at the organization level, providing both total counts and breakdowns by individual replicas to give you detailed insights into resource distribution.

Overview

The usage API provides three main endpoints:

Combined Usage (/usage) - Returns both conversation and knowledge base metrics in a single response
Conversation Usage (/usage/conversations) - Returns detailed conversation metrics for the current month
Knowledge Base Usage (/usage/knowledgeBaseEntries) - Returns knowledge base entry counts across all replicas

Key Features

Current Month Conversation Tracking

Conversations are counted based on chat history activity within the current calendar month. A conversation is only counted if it has at least one chat message in the current month, regardless of when the conversation was originally created.

Knowledge Base Entry Filtering

Knowledge base entries are filtered to include only entries with READY status, excluding any processing, failed, or incomplete entries.

Replica-Level Breakdown

All metrics include both organization totals and per-replica breakdowns, allowing you to understand usage distribution across your replicas.

Authentication

All usage endpoints require organization-level authentication using service tokens. User-specific authentication is optional but recommended for audit trails.

Response Format

All usage endpoints return a consistent response structure with:

success: true - Indicates successful request
Metric-specific data with totals and replica breakdowns
Non-negative integer counts for all metrics

Date Boundaries

Conversation metrics use precise calendar month boundaries:

Start of Month: First day at 00:00:00.000
End of Month: Last day at 23:59:59.999

All dates and times are in UTC.

Conversations spanning multiple months are counted in the month where they have chat activity.

Data Isolation

Usage metrics are strictly isolated by organization. Each organization can only access its own usage data, ensuring complete data privacy and security.

Error Handling

Usage endpoints return standard HTTP status codes:

200 OK - Successful request with usage data
401 Unauthorized - Invalid or missing authentication credentials
500 Internal Server Error - Server-side processing errors

Rate Limiting

Usage endpoints are subject to standard API rate limits. For high-frequency monitoring, consider caching responses and implementing appropriate polling intervals.