Bot Usage Statistics

Understanding how your bots consume resources is essential for managing costs, optimizing performance, and making informed decisions about scaling and resource allocation. Bot usage statistics provide comprehensive metrics that track token consumption, conversation counts, and message volumes, giving you visibility into how each bot is being used and what resources it's consuming.

These statistics are particularly valuable for production environments where multiple bots may be serving different use cases with varying levels of activity. By monitoring usage patterns, you can identify high-traffic bots that may need optimization, detect unusual activity patterns that could indicate issues, and forecast future resource needs based on historical trends.

Fetching Bot Usage Statistics

To retrieve usage statistics for a specific bot, you can query the usage endpoint with optional date range filters. The endpoint returns aggregated metrics including total tokens consumed (BASE type only), total number of conversations initiated, and total messages exchanged during the specified period.

By default, the statistics cover up to the last 90 days of activity. You can narrow this range by specifying start and end dates to focus on specific time periods, which is useful for generating reports, analyzing trends over specific intervals, or investigating usage patterns during particular events or campaigns.

To filter statistics by date range, include from and to query parameters with ISO 8601 formatted dates:

The response includes three key metrics:

• tokens: Total number of BASE-type tokens consumed by the bot during the period. This includes both input tokens (from user messages and context) and output tokens (from bot responses). Token counts are the primary basis for usage-based billing.

• conversations: Total number of unique conversations initiated with the bot. This metric helps you understand engagement levels and how many distinct users or sessions are interacting with your bot.

• messages: Total number of messages exchanged in conversations with the bot. This includes both user messages and bot responses, providing insight into conversation depth and interaction patterns.

Important Considerations:

• Date ranges are automatically clamped to a maximum of 90 days in the past to ensure query performance. Requests for older data will be adjusted to start from the 90-day threshold.

• The from date must be earlier than or equal to the to date. If the dates are reversed, the system will automatically use the later date as both the start and end, effectively returning statistics for a single point in time.

• Usage statistics are aggregated from transaction logs and may take a few minutes to reflect the most recent activity. For real-time monitoring of active conversations, use the conversation list endpoints instead.

• Token counts represent BASE token types only. Different AI models may have different token counting methods and pricing tiers, so always refer to your billing dashboard for accurate cost calculations.