Using DataHub Audit APIs to Track User Activity and Token Events – DataHub Customer Support Portal

Area: API Issues

Sub-Area: Audit Logging and Analytics Endpoints

Issue

When attempting to build a comprehensive audit trail of user behavior in DataHub Cloud, users may find that the /openapi/v1/events/audit/search endpoint does not capture all expected event types. Notably, events such as token creation and revocation may not appear as standalone named events, and granular UI-level activity — such as which pages a user visited or what search queries they executed — is not available through this endpoint at all. Understanding which API endpoints to use for different categories of audit data is essential for teams building complete user activity reports or compliance audit trails.

You Might Be Asking

Why doesn't /openapi/v1/events/audit/search return token creation events?
Is there an API to see which pages a user visited in DataHub?
How can I query the search queries a user executed in DataHub?
What is the difference between the v1 audit search endpoint and the v2 analytics endpoint?
How do I get a complete audit trail of all user actions in DataHub Cloud?

Solution

DataHub exposes user activity data through two distinct endpoints, each covering different categories of events. A comprehensive audit trail requires using both.

Understand the scope of each endpoint:
- /openapi/v1/events/audit/search — Covers backend-sourced administrative and compliance events: policy changes, user management, ingestion source events, and entity aspect mutations (including token creation and revocation). It does not capture frontend UI interactions such as page views or search queries.
- /openapi/v2/analytics/datahub_usage_events/_search — Provides access to the full datahub_usage_events Elasticsearch index, including all client-level events: page views, entity views, search queries, clicks, login/logout events, and more. This endpoint accepts Elasticsearch Query DSL in the request body.
Query token creation and revocation events via the v1 endpoint:
Token creation and revocation are captured as aspect mutation events on the dataHubAccessToken entity. To retrieve them, explicitly filter by entity type:
```
POST /openapi/v1/events/audit/search?size=100&includeRaw=true
Content-Type: application/json

{
  "entityTypes": ["dataHubAccessToken"]
}
```
Look for UPDATE_ASPECT_EVENT records where the aspectName field is dataHubAccessTokenInfo.

Query page views and search activity via the v2 analytics endpoint:

Use /openapi/v2/analytics/datahub_usage_events/_search with Elasticsearch DSL to query for specific event types. Your access token must have the ANALYTICS READ privilege.

Example: Retrieve search queries executed by users over the past day (Python):

import json
from datetime import datetime, timedelta
import requests

TOKEN = "<your-datahub-access-token>"
BASE_URL = "https://<your-instance>.acryl.io/gms"
DAYS_BACK = 1
PAGE_SIZE = 100

url = f"{BASE_URL}/openapi/v2/analytics/datahub_usage_events/_search"

now = datetime.utcnow()
start = now - timedelta(days=DAYS_BACK)
gte_ts = int(start.timestamp() * 1000)
lt_ts  = int(now.timestamp() * 1000)

payload = {
    "size": PAGE_SIZE,
    "query": {
        "bool": {
            "must": [
                {"range": {"timestamp": {"gte": gte_ts, "lt": lt_ts}}},
                {"term":  {"type": "SearchEvent"}}
            ]
        }
    },
    "sort": [{"timestamp": "desc"}]
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {TOKEN}",
    "accept": "application/json"
}

response = requests.post(url, data=json.dumps(payload), headers=headers)
response.raise_for_status()
hits = response.json()["hits"]["hits"]
for hit in hits:
    print(hit)

Example: Retrieve entity/page view events for a specific user:

payload = {
    "size": PAGE_SIZE,
    "query": {
        "bool": {
            "must": [
                {"range": {"timestamp": {"gte": gte_ts, "lt": lt_ts}}},
                {"term":  {"type": "EntityViewEvent"}},
                {"term":  {"actorUrn": "urn:li:corpuser:<username>"}}
            ]
        }
    },
    "sort": [{"timestamp": "desc"}]
}

Each EntityViewEvent record includes the entity URN viewed, entity type, timestamp, source IP, and user agent.

Reference: Event types available per endpoint
Use the table below to determine which endpoint to query for a given event category:
- v1 audit endpoint (/openapi/v1/events/audit/search):
  - Policy changes: CreatePolicyEvent, UpdatePolicyEvent, DeletePolicyEvent
  - Token creation/revocation: UpdateAspectEvent on dataHubAccessToken entity
  - Metadata edits: UpdateAspectEvent (any entity)
  - User and group management events
  - Ingestion source events
- v2 analytics endpoint (/openapi/v2/analytics/datahub_usage_events/_search):
  - Login/logout: LogInEvent, LogOutEvent, FailedLogInEvent
  - Pages visited: PageViewEvent, EntityViewEvent, EntitySectionViewEvent
  - Searches executed: SearchEvent, SearchResultClickEvent
  - Entity interactions: EntityActionEvent

Additional Notes

The v1 audit search endpoint is intentionally scoped to backend-sourced administrative events and is designed for compliance and governance use cases. The v2 analytics endpoint provides broader coverage of user behavioral data but uses raw Elasticsearch Query DSL, making it less structured. The ANALYTICS READ privilege is required on your DataHub access token to query the v2 analytics endpoint. When filtering for token-related events in the v1 endpoint, the absence of a standalone CreateAccessTokenEvent type is by design — token lifecycle changes are tracked as aspect mutations on the dataHubAccessToken entity. Pagination should be implemented for large result sets; the size parameter and Elasticsearch from/search_after patterns are supported on the v2 endpoint.

Issue

You Might Be Asking

Solution

Additional Notes

Related Documentation