Audit Logs
The audit logs feature defines structured account-scoped operation events for execution history and troubleshooting. It gives you a reliable trace of who did what and what happened next.
Why This Matters
This feature preserves an auditable trail across credential, task, job, and email operations so incident review is based on concrete execution history. It combines account-scoped access with searchable log fields and explicit cleanup operations to keep diagnostics reliable over time.
Core Flow
Operational actions emit structured log events with subject and action fields, which operators query through list and search routes during troubleshooting. Detailed log reads and scoped cleanup calls remain explicit operations.
Operations
| Operation | Endpoint | Purpose |
|---|---|---|
| Create log | POST /api/accounts/:account_id/logs | Write structured operation event |
| List logs | GET /api/accounts/:account_id/logs | Retrieve account log stream |
| Search logs | POST /api/accounts/:account_id/logs/search | Query logs by event criteria |
| Delete logs by search | POST /api/accounts/:account_id/logs/search-delete | Bulk cleanup matched logs |
| Get log | GET /api/logs/:log_id | Retrieve one log entry |
| Delete log | DELETE /api/logs/:log_id | Remove one log entry |
Key Data and State
{
id: "log_...",
account_id: "acc_...",
subject: "job",
action: "retry",
status: "failed",
data: { job_id: "job_...", error_code: "provider_timeout" }
}Failure Modes and Controls
Missing account scope or authorization rejects log reads and writes, and search-delete remains explicit and account-scoped to prevent accidental broad deletion. Structured fields preserve failure detail for deterministic debugging, while retrieval endpoints remain read-only and separate from mutation routes.