> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/guides/api-reference/audit-events.md).

# Audit Events

Read and export the organization audit log.

## List Audit Events

> ListAuditEvents lists audit events, newest first. Supports AIP-160 filtering\
> (event\_type, category, actor, workspace\_id, event\_time range, status,\
> credits\_delta) and keyset pagination.\
> \
> Audit logs are an org-level object: this single org-scoped endpoint serves\
> every caller, and the server RBAC-filters the returned rows by the caller's\
> roles across the org (org owners see every tier across all workspaces;\
> workspace admins/authors see their workspaces' events at their tier).\
> Workspace is a \`workspace\_id\` filter, not a path.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Audit Events","description":"Read and export the organization audit log."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAuditEventsResponse":{"type":"object","properties":{"audit_events":{"type":"array","items":{"$ref":"#/components/schemas/v1AuditEvent"},"description":"The page of audit events, ordered per the request (newest first by default)."},"next_page_token":{"type":"string","description":"A token to retrieve the next page, or empty if there are no more results."}},"description":"Response message for ListAuditEvents."},"v1AuditEvent":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the audit event. Audit logs are org-level, so the name\nis always org-scoped (workspace is an attribute/filter, not part of the name).\nFormat: organizations/{organization}/auditEvents/{audit_event}"},"event_time":{"type":"string","format":"date-time","description":"The time when the action occurred.","readOnly":true},"workspace_id":{"type":"string","description":"The workspace associated with the event, if any (the UI \"Location\").","readOnly":true},"category":{"type":"string","description":"The broad category of the event (string name of the category enum).","readOnly":true},"event_type":{"type":"string","description":"The specific event type (string name of the event-type enum).","readOnly":true},"action":{"type":"string","description":"A free-form verb describing the action (e.g. \"create\", \"rename\").","readOnly":true},"actor":{"$ref":"#/components/schemas/v1AuditActor"},"resource_name":{"type":"string","description":"The AIP resource name of the affected object, if any.","readOnly":true},"before_json":{"type":"string","description":"JSON snapshot of the relevant state before the change (for updates).","readOnly":true},"after_json":{"type":"string","description":"JSON snapshot of the relevant state after the change (for creates/updates).","readOnly":true},"status":{"$ref":"#/components/schemas/v1AuditStatus"},"credits_delta":{"type":"number","format":"double","description":"Signed credit delta for the event, if it affected credits\n(negative = consumed, positive = added).","readOnly":true},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary additional context (e.g. source IP, integration name).","readOnly":true},"source_service":{"type":"string","description":"The service that emitted this event (e.g. \"agora\", \"grimoire\").","readOnly":true}},"description":"AuditEvent is a single recorded action in the audit log."},"v1AuditActor":{"type":"object","properties":{"user_id":{"type":"string","description":"The unique identifier of the acting user, if a user initiated the action."},"display_name":{"type":"string","description":"Human-readable display name of the actor at the time of the event."},"email":{"type":"string","description":"Email of the acting user at the time of the event."},"actor_type":{"$ref":"#/components/schemas/v1AuditActorType"},"pat_id":{"type":"string","description":"The personal access token id, if the action was performed via a PAT."}},"description":"AuditActor identifies who performed an audited action."},"v1AuditActorType":{"type":"string","enum":["AUDIT_ACTOR_TYPE_UNSPECIFIED","AUDIT_ACTOR_TYPE_USER","AUDIT_ACTOR_TYPE_SERVICE","AUDIT_ACTOR_TYPE_SYSTEM","AUDIT_ACTOR_TYPE_SUPPORT"],"default":"AUDIT_ACTOR_TYPE_UNSPECIFIED","description":"AuditActorType classifies the kind of actor that performed an action.\nMirrors common.v1.AuditActorType (the Kafka payload enum).\n\n - AUDIT_ACTOR_TYPE_UNSPECIFIED: Actor type is not specified.\n - AUDIT_ACTOR_TYPE_USER: A human user.\n - AUDIT_ACTOR_TYPE_SERVICE: Another Kognitos service acting on its own behalf.\n - AUDIT_ACTOR_TYPE_SYSTEM: The platform itself (automated/system-initiated action).\n - AUDIT_ACTOR_TYPE_SUPPORT: A Kognitos support/staff user acting on a customer's behalf."},"v1AuditStatus":{"type":"string","enum":["AUDIT_STATUS_UNSPECIFIED","AUDIT_STATUS_SUCCESS","AUDIT_STATUS_FAILURE","AUDIT_STATUS_PENDING"],"default":"AUDIT_STATUS_UNSPECIFIED","description":"AuditStatus is the outcome of an audited action.\n\n - AUDIT_STATUS_UNSPECIFIED: Status is not specified.\n - AUDIT_STATUS_SUCCESS: The action completed successfully.\n - AUDIT_STATUS_FAILURE: The action failed.\n - AUDIT_STATUS_PENDING: The action is in progress / pending an outcome."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/auditEvents":{"get":{"summary":"List Audit Events","description":"ListAuditEvents lists audit events, newest first. Supports AIP-160 filtering\n(event_type, category, actor, workspace_id, event_time range, status,\ncredits_delta) and keyset pagination.\n\nAudit logs are an org-level object: this single org-scoped endpoint serves\nevery caller, and the server RBAC-filters the returned rows by the caller's\nroles across the org (org owners see every tier across all workspaces;\nworkspace admins/authors see their workspaces' events at their tier).\nWorkspace is a `workspace_id` filter, not a path.","operationId":"ListAuditEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAuditEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of events to return. The service may return fewer.\nIf unspecified, at most 50 are returned; the maximum is 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token from a previous ListAuditEvents call. Provide it to retrieve\nthe subsequent page. Keyset-based: encodes (event_time, id) of the last row.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"An AIP-160 filter expression. Supported fields: event_type, category,\nactor, workspace_id, event_time (range), status, credits_delta.","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Sort order. Only \"event_time desc\" (default) and \"event_time asc\" are\nsupported; the keyset cursor follows the chosen order.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Audit Events"]}}}}
```

## Get Audit Event

> GetAuditEvent retrieves a single audit event by resource name. Backs the\
> "copy link to this event" deep-link in the UI. The server applies the same\
> RBAC row-filtering as ListAuditEvents and returns NOT\_FOUND (never\
> PERMISSION\_DENIED) when the event is outside the caller's visibility, so\
> existence is not disclosed.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Audit Events","description":"Read and export the organization audit log."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AuditEvent":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the audit event. Audit logs are org-level, so the name\nis always org-scoped (workspace is an attribute/filter, not part of the name).\nFormat: organizations/{organization}/auditEvents/{audit_event}"},"event_time":{"type":"string","format":"date-time","description":"The time when the action occurred.","readOnly":true},"workspace_id":{"type":"string","description":"The workspace associated with the event, if any (the UI \"Location\").","readOnly":true},"category":{"type":"string","description":"The broad category of the event (string name of the category enum).","readOnly":true},"event_type":{"type":"string","description":"The specific event type (string name of the event-type enum).","readOnly":true},"action":{"type":"string","description":"A free-form verb describing the action (e.g. \"create\", \"rename\").","readOnly":true},"actor":{"$ref":"#/components/schemas/v1AuditActor"},"resource_name":{"type":"string","description":"The AIP resource name of the affected object, if any.","readOnly":true},"before_json":{"type":"string","description":"JSON snapshot of the relevant state before the change (for updates).","readOnly":true},"after_json":{"type":"string","description":"JSON snapshot of the relevant state after the change (for creates/updates).","readOnly":true},"status":{"$ref":"#/components/schemas/v1AuditStatus"},"credits_delta":{"type":"number","format":"double","description":"Signed credit delta for the event, if it affected credits\n(negative = consumed, positive = added).","readOnly":true},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Arbitrary additional context (e.g. source IP, integration name).","readOnly":true},"source_service":{"type":"string","description":"The service that emitted this event (e.g. \"agora\", \"grimoire\").","readOnly":true}},"description":"AuditEvent is a single recorded action in the audit log."},"v1AuditActor":{"type":"object","properties":{"user_id":{"type":"string","description":"The unique identifier of the acting user, if a user initiated the action."},"display_name":{"type":"string","description":"Human-readable display name of the actor at the time of the event."},"email":{"type":"string","description":"Email of the acting user at the time of the event."},"actor_type":{"$ref":"#/components/schemas/v1AuditActorType"},"pat_id":{"type":"string","description":"The personal access token id, if the action was performed via a PAT."}},"description":"AuditActor identifies who performed an audited action."},"v1AuditActorType":{"type":"string","enum":["AUDIT_ACTOR_TYPE_UNSPECIFIED","AUDIT_ACTOR_TYPE_USER","AUDIT_ACTOR_TYPE_SERVICE","AUDIT_ACTOR_TYPE_SYSTEM","AUDIT_ACTOR_TYPE_SUPPORT"],"default":"AUDIT_ACTOR_TYPE_UNSPECIFIED","description":"AuditActorType classifies the kind of actor that performed an action.\nMirrors common.v1.AuditActorType (the Kafka payload enum).\n\n - AUDIT_ACTOR_TYPE_UNSPECIFIED: Actor type is not specified.\n - AUDIT_ACTOR_TYPE_USER: A human user.\n - AUDIT_ACTOR_TYPE_SERVICE: Another Kognitos service acting on its own behalf.\n - AUDIT_ACTOR_TYPE_SYSTEM: The platform itself (automated/system-initiated action).\n - AUDIT_ACTOR_TYPE_SUPPORT: A Kognitos support/staff user acting on a customer's behalf."},"v1AuditStatus":{"type":"string","enum":["AUDIT_STATUS_UNSPECIFIED","AUDIT_STATUS_SUCCESS","AUDIT_STATUS_FAILURE","AUDIT_STATUS_PENDING"],"default":"AUDIT_STATUS_UNSPECIFIED","description":"AuditStatus is the outcome of an audited action.\n\n - AUDIT_STATUS_UNSPECIFIED: Status is not specified.\n - AUDIT_STATUS_SUCCESS: The action completed successfully.\n - AUDIT_STATUS_FAILURE: The action failed.\n - AUDIT_STATUS_PENDING: The action is in progress / pending an outcome."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/auditEvents/{audit_event_id}":{"get":{"summary":"Get Audit Event","description":"GetAuditEvent retrieves a single audit event by resource name. Backs the\n\"copy link to this event\" deep-link in the UI. The server applies the same\nRBAC row-filtering as ListAuditEvents and returns NOT_FOUND (never\nPERMISSION_DENIED) when the event is outside the caller's visibility, so\nexistence is not disclosed.","operationId":"GetAuditEvent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AuditEvent"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"audit_event_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Audit Events"]}}}}
```

## Export Audit Events

> ExportAuditEvents generates a downloadable export (e.g. CSV) of the audit\
> events matching a filter, returning a short-lived presigned URL. Applies the\
> same org-level RBAC row-filtering as ListAuditEvents.

```json
{"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Audit Events","description":"Read and export the organization audit log."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ExportAuditEventsResponse":{"type":"object","properties":{"download_uri":{"type":"string","description":"A short-lived presigned URI the client can GET to download the export.","readOnly":true},"expire_time":{"type":"string","format":"date-time","description":"The time at which download_uri expires.","readOnly":true}},"description":"Response message for ExportAuditEvents."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AuditServiceExportAuditEventsBody":{"type":"object","properties":{"filter":{"type":"string","description":"An AIP-160 filter expression scoping the export (same grammar as\nListAuditEvents). If empty, all events for the Organization are exported."},"format":{"$ref":"#/components/schemas/v1ExportFormat"}},"description":"Request message for ExportAuditEvents."},"v1ExportFormat":{"type":"string","enum":["EXPORT_FORMAT_UNSPECIFIED","EXPORT_FORMAT_CSV"],"default":"EXPORT_FORMAT_UNSPECIFIED","description":"The output format for an audit-log export.\n\n - EXPORT_FORMAT_UNSPECIFIED: Format is not specified; the server defaults to CSV.\n - EXPORT_FORMAT_CSV: Comma-separated values."}}},"paths":{"/api/v1/organizations/{organization_id}/auditEvents:export":{"post":{"summary":"Export Audit Events","description":"ExportAuditEvents generates a downloadable export (e.g. CSV) of the audit\nevents matching a filter, returning a short-lived presigned URL. Applies the\nsame org-level RBAC row-filtering as ListAuditEvents.","operationId":"ExportAuditEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ExportAuditEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditServiceExportAuditEventsBody"}}},"required":true},"tags":["Audit Events"]}}}}
```
