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 |
| 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.
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.
