# Tracking user access to Textual {% hint style="info" %} Required global permissions: * Manage users and user groups * View all datasets {% endhint %} Textual provides a REST API endpoint to track the following events that are related to user access and permissions: * User account is created * User account is removed * User logs into Textual * User fails to log into Textual * User attempts to perform an action that they do not have permission for * A permission set is created, updated, or deleted * Permissions are added or removed from a permission set * A permission set is added to or removed from a user or user group In the results, each event includes the following information: * Description of the action * The user who performed the action * When the action occurred To request the access and permission events, use the following endpoint: ## Search audit events > By default, the most recent 100 results will be returned.\ > \ > \*\*Adding filters to the request\*\*\ > \ > For each filter to add, use the following format:\ > \ > parameterName=value\ > \ > Use & to separate multiple filter values:\ > \ > parameter1Name=parameter1Value\¶meter2Name=parameter2Value\ > \ > \*\*Valid filter parameters\*\*\ > \ > You can filter the included events based on the following parameters:\ > \ > \event\_category\ - The general category of event.\ > For example, to filter the results to only include events related to permission sets:\ > \ > event\_category=PermissionSet\ > \ > You can provide multiple event category values.\ > For example, to filter the results to include events related to both assigned permissions and permission sets:\ > \ > event\_category=PermissionSet\&event\_category=AssignedPermissions\ > \ > \event\_type\ - The specific type of event.\ > To get the available event types, refer to Solar.Core.Enums.AuditEvents.AuditEventType.\ > For example, to filter the results to only include when a permission set was created:\ > \ > event\_type=PermissionSetCreated\ > \ > You can provide multiple event type values.\ > For example, to filter the results to include both when a permission set was created and when a permission set was updated:\ > \ > event\_type=PermissionSetCreated\&event\_type=PermissionSetUpdated\ > \ > \outcome\ - Whether the event was successful (\Success\) or failed (\Fail\).\ > For example, to filter the results to only include successful events:\ > \ > outcome=Success\ > \ > \created\_before\ - Used to only include events that occurred before the specified timestamp.\ > \ > The timestamp uses the ISO 8601 format (\yyyy-MM-dd'T'HH:mm:ssZ\).\ > For example, to filter the results to only include events that occurred before 6:30 PM UTC on August 1, 2023:\ > \ > created\_before=2023-08-01T18:30:00Z\ > \ > \created\_after\ - Used to only include events that occurred after the specified timestamp.\ > \ > The timestamp uses the ISO 8601 format (\yyyy-MM-dd'T'HH:mm:ssZ\).\ > For example, to filter the results to only include events that occurred after 10:00 AM UTC on July 27, 2023:\ > \ > created\_after=2023-07-27T10:00:00Z\ > \ > \include\_unidentified\_events\ - For self-hosted instances, whether to include events that do not have an identified user.\ > By default, is false. These events might be server-generated or might be related to an unauthenticated action.\ > To include events that do not have an identified user:\ > \ > include\_unidentified\_events=true\ > \ > \*\*Sample requests:\*\*\ > \ > First 100 results by most recent:\ > \ > GET /api/audit-events/search\ > \ > Returns the first 20 results for permission set events that were successful:\ > \ > GET /api/audit-events/search?limit=20\&event\_category=PermissionSet\&outcome=Success\ > \### Required Permissions\ > \ > \- \*\*Global:\*\* Manage Users And Groups, View All Datasets
```json {"openapi":"3.0.4","info":{"title":"Textual API","version":"vDev"},"tags":[{"name":"Audit Events","description":"Search and retrieve audit events related to user access, actions, and permissions within your organization."}],"security":[{}],"paths":{"/api/audit-events/search":{"get":{"tags":["Audit Events"],"summary":"Search audit events","description":"By default, the most recent 100 results will be returned.\n \n**Adding filters to the request**\n \nFor each filter to add, use the following format:\n \n parameterName=value\n \nUse & to separate multiple filter values:\n \n parameter1Name=parameter1Value¶meter2Name=parameter2Value\n \n**Valid filter parameters**\n \nYou can filter the included events based on the following parameters:\n \nevent_category - The general category of event.\nFor example, to filter the results to only include events related to permission sets:\n \n event_category=PermissionSet\n \nYou can provide multiple event category values.\nFor example, to filter the results to include events related to both assigned permissions and permission sets:\n \n event_category=PermissionSet&event_category=AssignedPermissions\n \nevent_type - The specific type of event.\nTo get the available event types, refer to Solar.Core.Enums.AuditEvents.AuditEventType.\nFor example, to filter the results to only include when a permission set was created:\n \n event_type=PermissionSetCreated\n \nYou can provide multiple event type values.\nFor example, to filter the results to include both when a permission set was created and when a permission set was updated:\n \n event_type=PermissionSetCreated&event_type=PermissionSetUpdated\n \noutcome - Whether the event was successful (Success) or failed (Fail).\nFor example, to filter the results to only include successful events:\n \n outcome=Success\n \ncreated_before - Used to only include events that occurred before the specified timestamp.\n \nThe timestamp uses the ISO 8601 format (yyyy-MM-dd'T'HH:mm:ssZ).\nFor example, to filter the results to only include events that occurred before 6:30 PM UTC on August 1, 2023:\n \n created_before=2023-08-01T18:30:00Z\n \ncreated_after - Used to only include events that occurred after the specified timestamp.\n \nThe timestamp uses the ISO 8601 format (yyyy-MM-dd'T'HH:mm:ssZ).\nFor example, to filter the results to only include events that occurred after 10:00 AM UTC on July 27, 2023:\n \n created_after=2023-07-27T10:00:00Z\n \ninclude_unidentified_events - For self-hosted instances, whether to include events that do not have an identified user.\nBy default, is false. These events might be server-generated or might be related to an unauthenticated action.\nTo include events that do not have an identified user:\n \n include_unidentified_events=true\n \n**Sample requests:**\n \nFirst 100 results by most recent:\n \n GET /api/audit-events/search\n \nReturns the first 20 results for permission set events that were successful:\n \n GET /api/audit-events/search?limit=20&event_category=PermissionSet&outcome=Success\n### Required Permissions\n\n- **Global:** Manage Users And Groups, View All Datasets\n","parameters":[{"name":"offset","in":"query","description":"Number of records to skip for pagination","schema":{"type":"integer","format":"int32"}},{"name":"limit","in":"query","description":"Maximum number of records to return","schema":{"type":"integer","format":"int32"}},{"name":"event_category","in":"query","description":"Filter by event category","schema":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventCategory"}}},{"name":"event_type","in":"query","description":"Filter by specific event type","schema":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventType"}}},{"name":"outcome","in":"query","description":"Filter by event outcome (Success or Fail)","schema":{"allOf":[{"$ref":"#/components/schemas/AuditEventOutcome"}]}},{"name":"created_before","in":"query","description":"Only include events before this timestamp (ISO 8601)","schema":{"type":"string","format":"date-time"}},{"name":"created_after","in":"query","description":"Only include events after this timestamp (ISO 8601)","schema":{"type":"string","format":"date-time"}},{"name":"include_unidentified_events","in":"query","description":"Include events without an identified user (self-hosted only)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Returns paginated audit events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventModelPaginationResponseModel"}}}},"400":{"description":"Invalid filter parameters or unsupported query option","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"AuditEventCategory":{"enum":["PermissionSet","AssignedPermissions","UserAuthentication","UserAccountManagement","Api"],"type":"string","description":"

Possible values:

\n\n"},"AuditEventType":{"enum":["UserCreated","UserRemoved","UserLogin","ApiAuthentication","ApiAuthorization","PermissionSetCreated","PermissionSetUpdated","PermissionSetDeleted","GlobalPermissionSetAssigned","GlobalPermissionSetRevoked","DatasetPermissionSetAssigned","DatasetPermissionSetRevoked"],"type":"string","description":"The specific type of audit event, such as user creation, login, or permission changes."},"AuditEventOutcome":{"enum":["Fail","Success"],"type":"string","description":"The status of the audit event. Some event types may only log Success or Fail events."},"AuditEventModelPaginationResponseModel":{"required":["records"],"type":"object","properties":{"offset":{"type":"integer","description":"The offset from the first item in the results. For example, 20 indicates that this batch of results starts with the 21st result.","format":"int32"},"limit":{"type":"integer","description":"The number of items the request limited the search to. The number of returned items can be less than the limit if not enough items exist or match the filter criteria.","format":"int32"},"pageNumber":{"type":"integer","description":"The number for this page of the results, starting at 1.","format":"int32"},"totalPages":{"type":"integer","description":"The total number of pages in the results.","format":"int32"},"totalRecords":{"type":"integer","description":"The total number of records in the results.","format":"int32"},"absoluteTotalRecords":{"type":"integer","description":"The absolute total number of records available (unfiltered). This represents the total count without any search or filter applied.","format":"int32"},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page of results."},"hasNextPage":{"type":"boolean","description":"Whether there is a next page of results."},"records":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventModel"},"description":"An array of returned records."}},"additionalProperties":false,"description":"Paginated response wrapper containing a page of results along with pagination metadata."},"AuditEventModel":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the audit event."},"timestamp":{"allOf":[{"$ref":"#/components/schemas/Instant"}],"description":"The time the event occurred."},"eventCategory":{"enum":["PermissionSet","AssignedPermissions","UserAuthentication","UserAccountManagement","Api"],"allOf":[{"$ref":"#/components/schemas/AuditEventCategory"}],"description":"The general category of the event (e.g. PermissionSet, AssignedPermissions).

Possible values:

\n\n"},"eventType":{"enum":["UserCreated","UserRemoved","UserLogin","ApiAuthentication","ApiAuthorization","PermissionSetCreated","PermissionSetUpdated","PermissionSetDeleted","GlobalPermissionSetAssigned","GlobalPermissionSetRevoked","DatasetPermissionSetAssigned","DatasetPermissionSetRevoked"],"allOf":[{"$ref":"#/components/schemas/AuditEventType"}],"description":"The specific type of event (e.g. PermissionSetCreated, PermissionSetUpdated)."},"outcome":{"enum":["Fail","Success"],"allOf":[{"$ref":"#/components/schemas/AuditEventOutcome"}],"description":"Whether the event was successful or failed."},"user":{"type":"string","description":"The user who performed or triggered the event."},"message":{"type":"string","description":"A human-readable description of the event."},"metadata":{"description":"Additional structured data associated with the event, if any.","nullable":true}},"additionalProperties":false,"description":"Contains the details for an audit event included in the results of a GET /api/audit-events/search request."},"Instant":{"type":"object","additionalProperties":false,"description":"A point in time represented as an ISO 8601 timestamp string."}}}} ```