←back to manuals

Usage Reports

Usage reports offer comprehensive insights into how you're using the ChatBotKit platform, including conversation volumes, message counts, resource consumption, and activity patterns. These reports are essential for understanding usage trends, monitoring costs, planning capacity, and demonstrating value to stakeholders.

Generating Usage Reports

The report generation endpoint creates detailed analytics reports that summarize your platform usage and performance metrics. These reports analyze your account's activity data, aggregate statistics across multiple dimensions, and return structured results that can be used for further analysis or visualization.

Reports support multiple types of analysis, each focusing on different aspects of your platform usage. You can request one or more report types in a single API call, and the system will generate all requested reports in parallel for efficiency.

Creating a Report

To generate usage reports, specify which report types you want and the time period for analysis. The endpoint accepts an array of report identifiers, each corresponding to a specific type of analysis such as conversation metrics, message counts, or resource utilization.

The endpoint returns an object where each key corresponds to a requested report type, and the value contains either the report data or an error message if that specific report couldn't be generated. This design allows partial success - some reports may complete successfully while others fail, and you'll receive all available data.

Available Report Types

The system supports various report types that analyze different aspects of your platform usage:

  • Conversation Reports: Analyze conversation volumes, patterns, and engagement metrics over time
  • Message Reports: Track message counts, types, and distribution across conversations and users
  • Integration Reports: Break down activity by integration type, showing which channels are most active
  • Resource Reports: Analyze which bots, datasets, and other resources are being used most frequently
  • Performance Reports: Track response times, completion rates, and other performance indicators

Each report type returns data in a consistent format optimized for the specific metrics being analyzed, making it easy to integrate with your existing analytics and visualization tools.

Time Period Specification

Report periods are specified using ISO 8601 timestamp format with timezone information. Both start and end timestamps are inclusive, meaning a report from "2025-01-01T00:00:00Z" to "2025-01-31T23:59:59Z" includes all activity throughout both January 1st and January 31st.

The timezone component of timestamps (indicated by 'Z' for UTC or a timezone offset like '+05:00') determines how date boundaries are interpreted. Using consistent timezones across reports ensures accurate day-to-day comparisons and trend analysis.

Report Generation Performance

Report generation analyzes potentially large volumes of activity data and may take several seconds to complete, especially for long time periods or accounts with high activity. The endpoint processes multiple report types in parallel when requested together, which is more efficient than making separate requests for each report type.

For optimal performance, consider these recommendations:

  • Limit Time Ranges: Reports covering 90 days or less typically generate faster than longer periods
  • Request Specific Reports: Only request the report types you need rather than generating all available reports
  • Cache Results: Store generated reports for reuse rather than regenerating the same analysis repeatedly
  • Batch Requests: Request multiple related report types in a single API call rather than making sequential requests

Error Handling

When generating multiple reports, each report is processed independently. If one report fails due to insufficient data, invalid parameters, or processing errors, other reports will still complete successfully. The response structure clearly indicates which reports succeeded and which encountered errors.

This partial success pattern ensures you receive all available data even if some reports encounter issues, allowing you to proceed with analysis using the successfully generated reports.

Best Practices

  • Regular Reporting: Generate reports on a consistent schedule (daily, weekly, or monthly) to track trends over time
  • Appropriate Granularity: Match report periods to your analysis needs - hourly for real-time monitoring, daily for operational reviews, monthly for strategic planning
  • Validation: Verify report data against known metrics to ensure accuracy, especially when setting up automated reporting workflows
  • Archive Results: Store generated report data for historical analysis and compliance purposes

Note: Report generation requires appropriate permissions and may be subject to rate limiting. Very large date ranges or complex report types may have extended processing times or require pagination for complete results.

Important: Report data reflects your account's activity as recorded in the platform's analytics systems. There may be a small delay (typically minutes) between an event occurring and it appearing in generated reports due to data processing pipelines.

reportsanalyticsusageexportmetrics