import FeatureAvailability from '@site/src/components/FeatureAvailability'; # Audit Events Search API V1 ## Endpoint `/openapi/v1/events/audit/search` ## Overview This API allows you to search for audit events that occur within DataHub. Audit events track various actions performed by users and systems, providing a comprehensive history of activities and changes within your DataHub instance. ## Request Structure The Audit Events Search API accepts POST requests with optional query parameters and a required JSON body. ### Query Parameters | Name | Type | Description | Required | Default | | ---------- | ------- | ----------------------------------------------------------------------- | -------- | ------- | | startTime | int64 | The timestamp (in ms) to start the search from, defaults to one day ago | No | -1 | | endTime | int64 | The timestamp (in ms) to end the search at, defaults to current time | No | -1 | | size | int32 | The maximum number of events to return in one response | No | 10 | | scrollId | string | The scroll ID used for pagination when fetching subsequent results | No | null | | includeRaw | boolean | Whether to include the raw event data in the response | No | true | ### Request Body The request body must be a JSON object with the following structure: ```json { "eventTypes": ["string"], "entityTypes": ["string"], "aspectTypes": ["string"], "actorUrns": ["string"] } ``` | Field | Type | Description | Required | | ----------- | -------- | -------------------------------------------------------------- | -------- | | eventTypes | string[] | List of event types to filter by (empty means all event types) | No | | entityTypes | string[] | List of entity types to filter by (empty means all entities) | No | | aspectTypes | string[] | List of aspect types to filter by (empty means all aspects) | No | | actorUrns | string[] | List of actor URNs to filter by (empty means all actors) | No | These filters work as `and` filters between each other and `or` filters for elements in the list so: ```json { "eventTypes": ["CreateAccessTokenEvent", "RevokeAccessTokenEvent"], "actorUrns": ["urn:li:corpuser:datahub"] } ``` Filters for events that are either `CreateAccessTokenEvent` or `RevokeAccessTokenEvent` AND had `urn:li:corpuser:datahub` as the actor. ## Response Structure The API returns a JSON object with the following structure: ```json { "nextScrollId": "string", "count": 0, "total": 0, "usageEvents": [ { // Event data varies based on event type } ] } ``` | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------ | | nextScrollId | string | ID for retrieving the next page of results (if more are available) | | count | int32 | Number of events returned in this response | | total | int32 | Total count of matching events (calculated up to 10,000) | | usageEvents | array | Array of usage events matching the search criteria | ## Event Types The API supports various event types that track different actions within DataHub. Each event type has its own specific structure, but all share common properties defined in the `UsageEventResult` base type. ### Common Fields (UsageEventResult) All event types include these base fields: | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------ | | eventType | string | Type of the event | | timestamp | int64 | Timestamp when the event occurred (in milliseconds) | | actorUrn | string | URN of the actor who performed the action | | sourceIP | string | IP address from which the action was performed | | eventSource | enum | Source API of the event (RESTLI, OPENAPI, GRAPHQL, SSO_SCIM) | | userAgent | string | User agent string from the HTTP request (if applicable) | | telemetryTraceId | string | Trace ID from system telemetry | | rawUsageEvent | object | Full raw event contents if includeRaw=true | ### Specific Event Types The API returns different event types, each with its own specific structure in addition to the common fields: #### EntityEvent Tracks general entity operations. ```json { "eventType": "EntityEvent", "timestamp": 1649953100653, "actorUrn": "urn:li:corpuser:jdoe", "sourceIP": "192.168.1.1", "eventSource": "GRAPHQL", "userAgent": "Mozilla/5.0...", "telemetryTraceId": "abc123", "entityUrn": "urn:li:dataset:abc", "entityType": "dataset", "aspectName": "ownership" } ``` #### Create/Update/Delete Event Types Several event types track specific creation, update, and deletion actions: - **CreateUserEvent**: Tracks user creation - **UpdateUserEvent**: Tracks user updates - **CreateAccessTokenEvent**: Tracks access token creation - **RevokeAccessTokenEvent**: Tracks access token revocation - **CreatePolicyEvent**: Tracks policy creation - **UpdatePolicyEvent**: Tracks policy updates - **CreateIngestionSourceEvent**: Tracks ingestion source creation - **UpdateIngestionSourceEvent**: Tracks ingestion source updates - **DeleteEntityEvent**: Tracks entity deletion - **UpdateAspectEvent**: Tracks aspect updates All these event types share the same structure: ```json { "eventType": "[Event Type Name]", "timestamp": 1649953100653, "actorUrn": "urn:li:corpuser:jdoe", "sourceIP": "192.168.1.1", "eventSource": "GRAPHQL", "userAgent": "Mozilla/5.0...", "telemetryTraceId": "abc123", "entityUrn": "urn:li:dataset:abc", "entityType": "dataset", "aspectName": "ownership" } ``` #### LogInEvent & FailedLogInEvent Tracks user login events with a specific login source. ```json { "eventType": "LogInEvent", "timestamp": 1649953100653, "actorUrn": "urn:li:corpuser:jdoe", "sourceIP": "192.168.1.1", "eventSource": "GRAPHQL", "userAgent": "Mozilla/5.0...", "telemetryTraceId": "abc123", "loginSource": "PASSWORD_LOGIN" } ``` `loginSource` can be one of: - PASSWORD_RESET - PASSWORD_LOGIN - FALLBACK_LOGIN - SIGN_UP_LINK_LOGIN - GUEST_LOGIN - SSO_LOGIN - OIDC_IMPLICIT_LOGIN ## Usage Examples ### Basic Search for All Events To search for all audit events with default parameters: ```json // POST /openapi/v1/events/audit/search { "eventTypes": [], "entityTypes": [], "aspectTypes": [], "actorUrns": [] } ``` ### Search for Events by a Specific User To search for all events performed by a specific user: ```json // POST /openapi/v1/events/audit/search { "eventTypes": [], "entityTypes": [], "aspectTypes": [], "actorUrns": ["urn:li:corpuser:jdoe"] } ``` ### Search for Specific Event Types with Time Range To search for specific event types within a time range: ```json // POST /openapi/v1/events/audit/search?startTime=1649953000000&endTime=1649954000000 { "eventTypes": ["LogInEvent", "CreateUserEvent"], "entityTypes": [], "aspectTypes": [], "actorUrns": [] } ``` ### Search for Events on Specific Entity Types To search for events related to specific entity types: ```json // POST /openapi/v1/events/audit/search { "eventTypes": [], "entityTypes": ["dataset", "dashboard"], "aspectTypes": [], "actorUrns": [] } ``` ### Paginating through Results To retrieve the first page of results: ```json // POST /openapi/v1/events/audit/search?size=25 { "eventTypes": [], "entityTypes": [], "aspectTypes": [], "actorUrns": [] } ``` To retrieve subsequent pages, use the `nextScrollId` from the previous response: ```json // POST /openapi/v1/events/audit/search?scrollId=abcdef123456&size=25 { "eventTypes": [], "entityTypes": [], "aspectTypes": [], "actorUrns": [] } ``` ## Best Practices 1. **Use Time Ranges**: Always specify start and end times when searching for events to limit the result set and improve performance. 2. **Filter Appropriately**: Use the filtering options (eventTypes, entityTypes, etc.) to narrow down your search to only the events you're interested in. 3. **Paginate Results**: Use the size parameter and scrollId to paginate through large result sets rather than trying to retrieve all events at once. 4. **Monitor User Activity**: Use the actorUrns filter to track actions by specific users, which is useful for security auditing.