←back to manuals

Event Logs

Event logs are the foundation of observability and operational intelligence in ChatBotKit, automatically capturing detailed information about every significant action, interaction, and state change across the platform. These logs provide a time-series record of system behavior that supports multiple critical use cases including real-time monitoring, historical analysis, debugging complex issues, compliance reporting, usage analytics, and billing reconciliation.

The event logging system operates transparently in the background, recording events from all major platform components including conversations, message exchanges, integration activities, bot interactions, dataset operations, skillset executions, and file processing. Each event captures relevant context including resource identifiers, event type, timestamp, metadata, and relationships to other platform objects, creating a comprehensive audit trail that can be queried, analyzed, and exported for various purposes.

Event logs are particularly valuable for understanding system behavior at scale, identifying performance bottlenecks, troubleshooting integration issues, generating usage reports, detecting anomalies, and ensuring platform reliability. The logs provide visibility into both successful operations and errors, making them essential for maintaining production systems and optimizing conversational AI deployments.

Listing Event Logs

The event log listing endpoint provides flexible querying capabilities for retrieving historical event data with comprehensive filtering, pagination, and ordering options. You can query events by various dimensions including time range, event type, associated resources, and custom metadata, enabling both broad operational monitoring and targeted investigation of specific scenarios or issues.

Event log queries support cursor-based pagination for efficient traversal of large result sets, with configurable page sizes and ordering (ascending or descending by timestamp). The endpoint can return data in both JSON and JSONL (JSON Lines) formats, with JSONL being particularly efficient for processing large volumes of events through streaming pipelines or batch analysis tools.

The response includes an array of event log entries, each containing:

  • Event metadata: Unique identifier, event type, creation timestamp
  • Resource associations: References to related bots, conversations, integrations, datasets
  • Context information: User ID, organization context, platform identifiers
  • Custom metadata: Event-specific data captured at the time of occurrence
  • Pagination data: Cursor tokens for retrieving subsequent pages

Filtering Event Logs

Event logs can be filtered by metadata fields using deep object notation, allowing you to query for specific types of events, resources, or conditions:

This filtering capability enables targeted queries for:

  • Resource-specific events: All events related to a particular bot, conversation, or integration
  • Event type filtering: Focus on specific categories like errors, completions, or status changes
  • Time-based analysis: Retrieve events within specific time windows for trend analysis
  • Custom attribute queries: Filter by any metadata field captured during event creation

Pagination and Performance

For optimal performance when working with large event log datasets, the endpoint implements cursor-based pagination. Use the cursor parameter with values returned from previous queries to traverse the result set efficiently:

Best Practices:

  • Use reasonable page sizes (50-500 events) to balance latency and data transfer
  • Implement cursor-based pagination for processing large event volumes
  • Filter events to reduce result set size when possible
  • Consider using JSONL format for bulk processing and analysis
  • Cache event log data when performing repeated queries
  • Use descending order (newest first) for monitoring recent activity

Use Cases:

  • Real-time operational monitoring and alerting
  • Troubleshooting conversation or integration issues
  • Generating usage and billing reports
  • Compliance and audit trail documentation
  • Performance analysis and optimization
  • Customer support investigation and debugging
  • Product analytics and feature usage tracking
  • Security monitoring and anomaly detection

Important Notes:

  • Event logs are retained according to your plan's data retention policy
  • High-volume applications should implement appropriate filtering and pagination
  • Event log queries count against API rate limits
  • Bulk exports may be more efficient for large historical analysis
  • Events are immutable once created and cannot be modified or deleted
  • Sensitive data may be redacted in event logs based on privacy settings
eventsloggingmonitoringauditanalytics