> ## Documentation Index > Fetch the complete documentation index at: https://studio.assembly.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List audit events > Returns a paginated list of audit log events for the authenticated workspace, optionally filtered by date range, event type, and actor. Requires internal-user privileges. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/events openapi: 3.0.0 info: contact: {} title: Assembly API version: 0.0.1 servers: - url: https://api.assembly.com security: [] paths: /v1/events: get: tags: - Events summary: List audit events description: >- Returns a paginated list of audit log events for the authenticated workspace, optionally filtered by date range, event type, and actor. Requires internal-user privileges. operationId: list-events parameters: - description: Inclusive start date filter (RFC3339) in: query name: startDate schema: format: date-time type: string - description: Inclusive end date filter (RFC3339) in: query name: endDate schema: format: date-time type: string - description: Comma-separated list of event types to filter by in: query name: eventType schema: type: string - description: Comma-separated list of actor IDs to filter by in: query name: actorId schema: type: string - description: Pagination cursor returned by a previous request. in: query name: nextToken schema: type: string - description: Maximum number of records to return. in: query name: limit schema: type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/audit_log.ListAuditLogsResponse' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Invalid pagination parameters '401': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Missing or invalid API key, or caller lacks internal-user privileges '500': content: application/json: schema: $ref: '#/components/schemas/dispatcher.Error' description: Unexpected server error security: - APIKeyHeader: [] components: schemas: audit_log.ListAuditLogsResponse: properties: data: items: $ref: '#/components/schemas/audit_log.AuditLog' type: array nextToken: description: base64 encoded JSON representing a NextToken type: string type: object dispatcher.Error: properties: code: type: string data: {} message: type: string type: object audit_log.AuditLog: properties: actorId: description: >- ActorID is the ID of the user or system actor that triggered the event. example: a1b2c3d4-e5f6-4711-8899-aabbccddeeff type: string actorRole: description: >- ActorRole is the normalized role of the actor (e.g. "admin", "staff"). Internal-only. example: admin type: string actorType: description: >- ActorType identifies whether the actor is an internal user or a client user. enum: - internalUser - clientUser example: internalUser type: string apiKeyRef: description: >- APIKeyRef references the API key used for platform-API-sourced events. Internal-only. example: key_01HZX8K9P2 type: string automationId: description: >- AutomationID is the ID of the automation that triggered the event, when applicable. example: auto_01HZX8K9P2 type: string companyId: description: >- CompanyID is the ID of the company the actor belongs to, when the actor is a client user. example: c1d2e3f4-a5b6-4712-9988-ffeeddccbbaa type: string context: additionalProperties: true description: >- Context carries event-specific metadata as arbitrary key/value pairs. type: object createdAt: type: string creatorId: type: string data: type: string eventDescription: description: EventDescription is a human-readable description of the event. example: Client created type: string eventDetails: example: Updated billing address type: string eventTextEntity: example: Acme Corp type: string eventTextPrefix: description: >- EventTextPrefix / EventTextEntity / EventDetails are computed at read time by FormatEvent (see event_formatter.go) and exposed to the internal audit log page and the CSV export so both render identical text. Not persisted, and tagged omitexternal — these are UI helpers, not part of the public platform API contract. Prefix and Entity intentionally omit `omitempty`: FormatEvent sets one of them to "" on purpose for events like messageSent (entity is the linked label, no prefix). With omitempty the empty string would drop from the wire, the client would `??` back to eventDescription, and the row would render as `Message sent "Message sent"` instead of a single linked `Message sent`. example: Client type: string eventType: allOf: - $ref: '#/components/schemas/audit_log.AuditEventType' description: EventType categorizes the event. example: clientCreated id: type: string identityId: type: string ip: description: IP is the client IP address that triggered the event. example: 203.0.113.42 type: string isSuperAdminTriggered: description: >- IsSuperAdminTriggered is set when the event originated from an Assembly super-admin proxy session (the admin signed in via /admin and is acting on behalf of a portal user). Hidden from external / platform-API consumers via omitexternal. example: false type: boolean object: type: string previousAttributes: additionalProperties: true type: object ref: type: string source: allOf: - $ref: '#/components/schemas/audit_log.Source' description: Source indicates where the event originated from. enum: - web - platform - automation - system example: web updatedAt: type: string userAgent: description: >- UserAgent is the User-Agent header of the request that triggered the event. UserAgent and IP are intentionally exposed to external consumers (no omitexternal tag). These fields contain PII; consumers are responsible for GDPR/CCPA compliance example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) type: string type: object audit_log.AuditEventType: enum: - userLoggedIn - userLoggedOut - userLoginSucceeded - userLoginFailed - passwordReset - passwordChanged - googleDelinked - magicLinkSent - workspaceMfaEnabled - workspaceMfaDisabled - clientCreated - clientActivated - clientUpdated - clientDeleted - clientInvited - companyCreated - companyUpdated - companyCustomFieldsUpdated - companyDeleted - clientCustomFieldsUpdated - fileCreated - fileUpdated - fileDeleted - folderCreated - folderUpdated - folderDeleted - linkCreated - linkUpdated - linkDeleted - invoiceCreated - invoiceInitiated - invoicePaid - invoiceUpdated - invoiceDeleted - invoiceVoided - invoiceDownloaded - refundRequested - refundSucceeded - refundFailed - messageSent - messageChannelCreated - messageChannelDeleted - taskCreated - taskUpdated - taskDeleted - taskArchived - taskCompleted - paymentSucceeded - paymentFailed - subscriptionCreated - subscriptionCancelled - priceCreated - productCreated - productUpdated - contractRequested - contractCompleted - contractDownloaded - fileDownloaded - fileBatchDownloaded - fileBatchDeleted - noteCreated - noteUpdated - noteDeleted - internalUserCreated - internalUserDeleted - internalUserAccessLevelChanged - internalUserClientVisibilitySet - apiKeyCreated - apiKeyDeleted - formCreated - formEdited - formAssigned - formResponseCompleted - customEvent - sessionStarted - sessionEnded type: string x-enum-varnames: - EventUserLoggedIn - EventUserLoggedOut - EventUserLoginSucceeded - EventUserLoginFailed - EventPasswordReset - EventPasswordChanged - EventGoogleDelinked - EventMagicLinkSent - EventWorkspaceMfaEnabled - EventWorkspaceMfaDisabled - EventClientCreated - EventClientActivated - EventClientUpdated - EventClientDeleted - EventClientInvited - EventCompanyCreated - EventCompanyUpdated - EventCompanyCustomFieldsUpdated - EventCompanyDeleted - EventClientCustomFieldsUpdated - EventFileCreated - EventFileUpdated - EventFileDeleted - EventFolderCreated - EventFolderUpdated - EventFolderDeleted - EventLinkCreated - EventLinkUpdated - EventLinkDeleted - EventInvoiceCreated - EventInvoiceInitiated - EventInvoicePaid - EventInvoiceUpdated - EventInvoiceDeleted - EventInvoiceVoided - EventInvoiceDownloaded - EventRefundRequested - EventRefundSucceeded - EventRefundFailed - EventMessageSent - EventMessageChannelCreated - EventMessageChannelDeleted - EventTaskCreated - EventTaskUpdated - EventTaskDeleted - EventTaskArchived - EventTaskCompleted - EventPaymentSucceeded - EventPaymentFailed - EventSubscriptionCreated - EventSubscriptionCancelled - EventPriceCreated - EventProductCreated - EventProductUpdated - EventContractRequested - EventContractCompleted - EventContractDownloaded - EventFileDownloaded - EventFileBatchDownloaded - EventFileBatchDeleted - EventNoteCreated - EventNoteUpdated - EventNoteDeleted - EventInternalUserCreated - EventInternalUserDeleted - EventInternalUserAccessLevelChanged - EventInternalUserClientVisibilitySet - EventAPIKeyCreated - EventAPIKeyDeleted - EventFormCreated - EventFormEdited - EventFormAssigned - EventFormResponseCompleted - EventCustomEvent - EventSessionStarted - EventSessionEnded audit_log.Source: enum: - web - platform - automation - system type: string x-enum-varnames: - SourceWeb - SourcePlatform - SourceAutomation - SourceSystem securitySchemes: APIKeyHeader: in: header name: X-API-KEY type: apiKey ````