Audit Logs
Track every significant action across your organization with filterable, paginated audit logs for compliance and debugging.
Audit logs record significant actions taken within an organization. Every export, GDPR deletion, configuration change, and other noteworthy events is captured with the acting user, IP address, and timestamp. The audit trail provides a chronological record for compliance auditing and operational debugging.
Overview
Each audit log entry contains:
- Action: the type of event that occurred (e.g.
export.conversations,gdpr.data_deletion) - User: who performed the action (can be null if the user has been deleted)
- Resource type and ID: what was affected
- Details: additional context as a JSON object
- IP address: the originating IP
- Timestamp: when the event occurred
Logs are scoped to the organization and ordered by most recent first.
Querying Audit Logs
GET /api/audit-logs?page=1&pageSize=50&userId=user-uuid&action=export.conversations&since=2025-01-01T00:00:00ZQuery Parameters
| Parameter | Type | Description |
|---|---|---|
page | number | Page number, starting at 1 (default: 1) |
pageSize | number | Items per page, 1 to 100 (default: 50) |
userId | UUID | Filter by specific user |
action | string | Filter by action type |
resourceType | string | Filter by resource type |
since | datetime | ISO 8601 timestamp, only show logs after this time |
Response
{
"auditLogs": [
{
"id": "log-uuid",
"orgId": "org-uuid",
"userId": "user-uuid",
"action": "export.conversations",
"resourceType": "conversation",
"resourceId": "conv-uuid",
"details": {
"format": "csv",
"recordCount": 150
},
"ipAddress": "203.0.113.42",
"createdAt": "2025-03-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"pageSize": 50,
"total": 234
}
}Common Action Types
Audit logs are written automatically by various parts of the system. These are the most common action types you will see:
Export Actions
| Action | Description |
|---|---|
export.conversations | Conversation data exported |
export.analytics | Analytics summary exported |
export.visitors | Visitor list exported |
export.conversations.bulk | Bulk filtered export |
GDPR Actions
| Action | Description |
|---|---|
gdpr.data_export | User data portability export |
gdpr.data_deletion | User data erasure completed |
Canned Response Actions
| Action | Description |
|---|---|
canned-response.category-rename | Category renamed across responses |
canned-response.category-delete | Category deleted or moved |
Filtering Strategies
Use the query parameters to narrow down the audit trail for specific investigations.
By User
Find everything a specific operator did:
GET /api/audit-logs?userId=op-123&page=1&pageSize=100By Action Type
Find all data exports across the organization:
GET /api/audit-logs?action=export.conversations&since=2025-01-01T00:00:00ZBy Time Range
Find all audit events from the last week:
GET /api/audit-logs?since=2025-03-08T00:00:00ZCombine multiple filters for precise results:
GET /api/audit-logs?userId=op-123&action=export.conversations&since=2025-03-01T00:00:00ZUser Reference
When a user's data is deleted via GDPR erasure, the userId field in
audit logs is set to null. The log entry itself is preserved but the
actor becomes anonymous. Use the IP address and timestamp to correlate
events when needed.
API Reference
| Method | Endpoint | Description |
|---|---|---|
GET | /api/audit-logs | List audit logs with filters and pagination |
Authentication required. Results are scoped to the authenticated user's organization.
Related
- GDPR Compliance: actions are logged in the audit trail
- Data Export: each export creates an audit entry
- Automation Rules: track rule changes and deletions
Was this page helpful?