Audit Logs

Audit logs are essential for maintaining security, compliance, and operational transparency by automatically recording every significant action performed in your ChatBotKit account. Each log entry captures detailed information about what action was performed, who performed it, when it occurred, and what resources were affected.

Understanding Audit Logs

Audit logs capture a wide range of activities including resource creation, updates, deletions, and access operations. Each audit log entry includes:

• Action details: The type of operation performed (create, update, delete, etc.)
• Resource information: The specific resources affected by the action
• User context: Who performed the action and from which IP address
• Temporal data: Precise timestamps for when the action occurred
• Change tracking: Old and new values for update operations
• Request metadata: User agent, session information, and other contextual data

This comprehensive logging enables you to track user behavior, investigate security incidents, meet compliance requirements, and understand how your resources are being used and modified over time.

Listing Audit Logs

To retrieve audit logs for your account, you can query the audit log list endpoint with various filtering options to find specific activities or narrow down your search to particular resources or time periods.

You can filter audit logs by specific resources using query parameters:

Available filter parameters include:

• action: Filter by specific action types (create, update, delete, etc.)
• blueprintId, botId, datasetId: Filter by specific resource IDs
• recordId, skillsetId, abilityId: Filter by related resource IDs
• fileId, secretId, portalId: Filter by integration resources
• webhookId, sessionId: Filter by connection and session data
• cursor, order, take: Standard pagination parameters

The response includes detailed information about each logged action:

Use Cases for Audit Logs

Audit logs serve several critical purposes:

• Security Monitoring: Track unauthorized access attempts and suspicious activities
• Compliance Auditing: Meet regulatory requirements for activity logging and data governance
• Troubleshooting: Investigate issues by reviewing recent changes to configurations
• Usage Analysis: Understand how resources are being utilized and modified
• Change Management: Track who made specific changes and when they occurred
• Accountability: Maintain clear records of all system modifications

Important: Audit logs are read-only and cannot be modified or deleted. They provide an immutable record of account activity for security and compliance purposes. Logs are retained according to your account's data retention policy.

Exporting Audit Logs

The audit log export functionality provides flexible options for extracting audit data in multiple formats, enabling integration with external analysis tools, compliance reporting systems, and long-term archival solutions. This endpoint supports exporting audit logs in JSON, JSONL (newline-delimited JSON), and CSV formats, each optimized for different use cases and downstream processing requirements.

Unlike the standard list endpoint, the export endpoint is specifically designed for bulk data extraction and includes special formatting that makes the exported data more suitable for analysis and reporting. Complex nested data structures like metadata, old values, and new values are automatically converted to YAML format within CSV exports for improved readability, while JSON and JSONL exports preserve the full nested structure for programmatic processing.

Export Formats

The export endpoint supports three output formats, each serving different analytical and integration needs:

JSON Format - Ideal for programmatic processing and API integrations:

Returns a standard JSON array wrapped in an object, suitable for direct consumption by JavaScript applications and REST API clients.

JSONL Format - Optimized for streaming and large dataset processing:

Returns newline-delimited JSON where each line represents a single audit log entry. This format is ideal for streaming processing, large dataset handling, and integration with log processing tools like Logstash, Fluentd, or custom stream processors. Each line is a complete, parseable JSON object that can be processed independently.

CSV Format - Best for spreadsheet analysis and reporting:

Returns a comma-separated values file that can be directly opened in Excel, Google Sheets, or other spreadsheet applications. Complex nested fields (meta, oldValues, newValues) are automatically converted to YAML format for improved readability in spreadsheet cells.

Filtering and Pagination

The export endpoint supports the same powerful filtering options as the list endpoint, allowing you to export only the specific audit logs you need:

Available filter parameters include:

• Action Filtering: action=create, action=update, action=delete
• Resource Filtering: botId, datasetId, skillsetId, blueprintId
• Related Resources: recordId, abilityId, fileId, secretId
• Connection Data: portalId, webhookId, sessionId
• Pagination: cursor, order (asc/desc), take (items per page)
• Metadata: meta[key]=value for custom metadata filtering

Large Dataset Exports

For exporting large volumes of audit logs, use cursor-based pagination with the JSONL format for optimal performance:

The JSONL format allows you to process each exported chunk as a stream, making it possible to export and process millions of audit log entries without excessive memory consumption. Each response includes a cursor value that you can use to fetch the next batch of results.

Use Cases for Audit Log Exports

Compliance Reporting: Export audit logs in CSV format for quarterly or annual compliance reports. The human-readable YAML formatting of complex fields makes it easy to review changes in spreadsheet applications.

Security Analysis: Export logs in JSONL format and pipe them into security information and event management (SIEM) tools for threat detection and anomaly analysis.

Data Archival: Periodically export audit logs in JSON format for long-term archival in your organization's document management or backup systems, ensuring compliance with data retention policies.

Change Tracking: Export logs filtered by specific resources (like a particular bot or dataset) to understand the complete change history and evolution of that resource over time.

Analytics and Reporting: Export logs in CSV format for analysis in business intelligence tools, allowing you to create custom reports on user activity, resource modifications, and system usage patterns.

Special Formatting for CSV Exports

When exporting to CSV format, the endpoint automatically applies special formatting to enhance readability:

• Nested Objects: The meta, oldValues, and newValues fields are converted to YAML format, making them readable in spreadsheet cells
• Timestamps: Date fields are formatted as ISO 8601 strings
• Resource IDs: All ID fields are preserved as-is for reference
• IP and User Agent: Network information is included in dedicated columns

This formatting makes CSV exports immediately useful for manual review and analysis in spreadsheet applications without requiring additional data transformation.

Important: Exported audit logs are snapshots of the data at the time of export. They do not automatically update when new logs are created. For continuous monitoring, consider building a scheduled export process that regularly fetches new logs using cursor-based pagination and the createdAt timestamp filters.

Performance Note: For optimal performance when exporting large datasets, use the JSONL format with reasonable take values (recommended: 1000-5000 items per request) and implement cursor-based pagination. This approach ensures consistent performance and prevents timeouts when dealing with extensive audit log histories.