Retrieving User Search and Audit Activity via the Analytics API – DataHub Customer Support Portal

Area: API Issues

Sub-Area: Analytics and Audit Event Retrieval

Issue

Users attempting to retrieve search activity events — such as dataset searches performed by users in the DataHub UI — via the audit search API endpoint (/openapi/v1/events/audit/search) find that search-related event types are not available there. The audit search API covers authentication, policy, ingestion, and entity operation events (e.g., LogInEvent), but it does not expose UI interaction events such as SearchEvent, EntityViewEvent, or SearchResultClickEvent. These usage and behavioral analytics events are served by a separate endpoint.

Error Messages

No results returned for SearchEvent queries against /openapi/v1/events/audit/search

You Might Be Asking

Why can't I find a SearchEvent type in the /openapi/v1/events/audit/search API documentation?
How do I retrieve records of which datasets users have searched for in DataHub?
What is the correct API endpoint to query DataHub UI usage and behavioral analytics events?
What event types are available in the DataHub usage analytics index?

Solution

Understand the two separate event sources:
- /openapi/v1/events/audit/search — Returns structured audit trail events for administrative and system-level actions: authentication (LogInEvent, FailedLogInEvent), user management, access token management, policy changes, ingestion source changes, and entity/aspect operations. This endpoint requires the calling token to have the ANALYTICS group READ privilege.
- /openapi/v2/analytics/datahub_usage_events/_search — Returns UI and behavioral usage events captured from user interactions. This is the correct endpoint for search activity and includes the following event types:
  - SearchEvent
  - SearchResultClickEvent
  - EntityViewEvent
  - EntityActionEvent
  - EntitySectionViewEvent
  - SelectAutoCompleteOption
  - HomePageTemplateModuleAssetClick
  - LogInEvent (also mirrored here)

Use the following Python script to retrieve SearchEvent records from the usage analytics endpoint. Replace <your-token> with a valid DataHub access token and <your-instance> with your DataHub instance hostname. Adjust DAYS_BACK as needed.

import json
from datetime import datetime, timedelta
from datahub.sdk import DataHubClient

TOKEN = "<your-token>"

# ── CONFIG ────────────────────────────────────────────────────────────────────
DAYS_BACK = 7
PAGE_SIZE = 100

# ── SETUP ─────────────────────────────────────────────────────────────────────
client = DataHubClient(
    server="https://<your-instance>/gms",
    token=TOKEN
)
url = f"{client._graph._gms_server}/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)

# ── QUERY ─────────────────────────────────────────────────────────────────────
def pull_analytics(search_after=None):
    payload = {
        "size": PAGE_SIZE,
        "query": {
            "bool": {
                "must": [
                    {"range": {"timestamp": {"gte": gte_ts, "lt": lt_ts}}},
                    {"term":  {"type": "SearchEvent"}}
                ]
            }
        },
        "sort": [{"timestamp": "desc"}],
    }
    if search_after:
        payload["search_after"] = [str(search_after)]

    response = client._graph._session.post(
        url,
        data=json.dumps(payload),
        headers={
            "Content-Type": "application/json",
            "accept": "application/json"
        },
    )
    response.raise_for_status()
    hits = response.json()["hits"]["hits"]
    return hits, (hits[-1]["sort"][0] if hits else None)

# ── COLLECT ───────────────────────────────────────────────────────────────────
all_events = []
print(
    f"Querying SearchEvents — last {DAYS_BACK} days "
    f"({start.strftime('%Y-%m-%d')} → {now.strftime('%Y-%m-%d')}) ...\n"
)

hits, last_sort = pull_analytics()
while hits:
    for hit in hits:
        src = hit.get("_source", hit)
        username = src.get("corp_user_username") or src.get("actorUrn", "")
        # Skip system/service accounts
        if not username or any(s in username for s in ["admin", "__datahub_system"]):
            continue
        all_events.append(src)
    if not last_sort:
        break
    hits, last_sort = pull_analytics(last_sort)

# ── REPORT ────────────────────────────────────────────────────────────────────
print("=" * 90)
print(f"SEARCH EVENTS — LAST {DAYS_BACK} DAYS ({len(all_events)} total)")
print("=" * 90)

for i, event in enumerate(all_events, 1):
    print(f"\n{'─' * 90}")
    print(f" EVENT #{i}")
    print(f"{'─' * 90}")
    for key, value in sorted(event.items()):
        print(f"  {key:<40} {json.dumps(value)}")

print(f"\n{'=' * 90}")
print(f"Total SearchEvents: {len(all_events)}")
print("=" * 90)

To query a different event type, change the term filter value in the query payload. For example, to retrieve entity view activity:
```
{"term": {"type": "EntityViewEvent"}}
```
To paginate through large result sets, the script automatically uses the search_after cursor mechanism. The last sort value from each page of results is passed as the cursor to the next request. Ensure PAGE_SIZE does not exceed 500 events per request.
Verify access token permissions. If the API returns empty results or a 403 error, confirm that the DataHub access token used has the required privileges. For the /openapi/v1/events/audit/search endpoint, the token must be granted ANALYTICS group READ privilege via a DataHub policy. Admin tokens do not automatically carry this privilege — it must be explicitly configured.

Additional Notes

The /openapi/v1/events/audit/search endpoint is focused on administrative and compliance audit trails and does not surface UI behavioral analytics such as search queries. The /openapi/v2/analytics/datahub_usage_events/_search endpoint is the preferred source for user activity analytics including search, navigation, and entity interaction events. Every usage event captures fields such as actorUrn, corp_user_username, timestamp, and event-specific metadata. The script above filters out internal system accounts (admin, __datahub_system) to surface only real user activity. DataHub Cloud manages all underlying retention and infrastructure for both APIs; customers interact solely through the API layer. If you are using DataHub's AI/Ask DataHub features, AI tool invocation audit data is available separately via GraphQL and requires the MANAGE_GLOBAL_SETTINGS privilege.

Issue

Error Messages

You Might Be Asking

Solution

Additional Notes

Related Documentation