Query events associated with your organization
/v1/audit-logsorg.permission.audit_logs.readorg.admin.audit_logs.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Audit logs
The audit log is a read-only history of what happened in your Kustomer org, such as who changed a conversation, who signed in, and what a routing or business rule did. Each entry records the event, the object it touched, who or what did it, and the fields that changed.
Kustomer writes an audit log entry whenever something notable happens to the data in your org: a conversation or customer is updated or deleted, a user signs in or fails to, a business rule is created, a work item is routed, a message is created. Admins see these entries in the audit log screen of the Kustomer admin settings, and the API exposes the same history so you can export it to a SIEM, investigate an incident, or answer "who changed this, and when?". Entries are created only by Kustomer. You can't write, edit or delete them, and each one expires after a retention period, shown in expiresAt.
What an entry contains
Each entry has type audit_log and these key attributes:
| Field | Meaning |
|---|---|
eventName |
The full event, such as kustomer.conversation.update or kustomer.user-auth.fail. |
eventVerb |
The action alone, such as create, update or delete. |
objectType, objectId |
The object the event is about. |
userId, userType |
Who did it. userType is system and userId is null when Kustomer itself made the change, for example during routing. |
client |
The part of Kustomer the change came from, such as routing. |
ip |
The caller's IP address, when known. |
changes |
For updates, a diff split into attributes and relationships. Each changed field has op, before and after. |
publishedAt, createdAt |
When the event happened and when it was recorded. |
Filtering
Narrow results with filter[objectType] (one of the types in the enum, such as conversation, customer, user, business_rule, work_item or work_session), then optionally filter[objectId] for one object. filter[userId] returns events by or about one user. filter[include] adds more object types to the results with OR logic, and filter[start] and filter[end] limit the date range. How far back you can search depends on your Kustomer plan.
Which endpoint to use
| To | Call |
|---|---|
| Search the org's audit history, by object, user or date | GET /v1/audit-logs |
Results come newest first and use cursor pagination rather than page numbers. count sets the page size (default 100, maximum 1000), and you move through pages with the before and after cursors, which are audit log IDs. The links.next and links.prev URLs in each response already contain the right cursor, so follow them instead of building cursors yourself. Reading the audit log requires the audit log read permission, which is usually limited to admins.
Query parameters
Limits the number audit-log documents to be returned. Default 100, maximum 1000.
100Paginates by the ID of the audit-log which marks the end of the pagination range. Requires "before".
"12398b37f821774356daa2a5"Paginates by the ID of the audit-log which marks the beginning of the pagination range. Requires "after".
"45698b37f821774356dcc2g1"Filters by the type of database object the event relates to.
bill_subscriptionbusiness_rulecompanyconversationcustomermessagesearchshortcutuserwork_itemip_rulework_sessionshopify_restFilters by the id of database object the event relates to. Requires filter[objectType].
"45698b37f821774356dcc2g1"Filters by the ID of the user the event relates to.
"45698b37f821774356dcc2g1"Adds additional OR query logic to include results for additional objectTypes. For available objectTypes to use in this query param, see the enum in the filter[objectType] field.
"user,shortcut,work_item,ip_rule"Filter by the date range start.
"2016-08-06T19:47:49.235Z"Filter by the date range end.
"2016-09-06T19:47:49.235Z"Responses
OK