Skip to main content

Quick Start Guide

This guide demonstrates basic usage of the H2O Audit Trail Python client with common operations.

tip

See the API documentation for full client reference.

note

The Python client only supports reading events via search_events(). Event creation methods (create_event() and batch_create_events()) return 405 Method Not Allowed errors. To maintain audit trail integrity, event creation is restricted to internal H2O AI Cloud services only.

Searching for events​

Here's a complete example that shows how to search for events:

from datetime import datetime, timezone, timedelta

import h2o_audit_trail
from h2o_audit_trail.event.search import SearchEventsRequestFilter

# Initialize the client
clients = h2o_audit_trail.login()
event_client = clients.event_client

# Search for events from the last 24 hours
search_response = event_client.search_events(
    filter_=SearchEventsRequestFilter(
        start_event_time=datetime.now(timezone.utc) - timedelta(days=1),
        principal_exact="users/john.doe"
    ),
    page_size=50
)

print(f"Found {len(search_response.events)} events")
for event in search_response.events:
    print(f"  - {event.action} at {event.event_time}")
    if event.metadata:
        print(f"    Metadata: {event.metadata}")

Common search patterns​

Searching by time range​

from datetime import datetime, timezone, timedelta

# Events from the last hour
response = event_client.search_events(
    filter_=SearchEventsRequestFilter(
        start_event_time=datetime.now(timezone.utc) - timedelta(hours=1)
    ),
    page_size=100
)

Searching by action​

# Find all CREATE actions
response = event_client.search_events(
    filter_=SearchEventsRequestFilter(
        action_regex=".*CREATE$"
    ),
    page_size=50
)

Searching by workspace​

# Events for a specific workspace
response = event_client.search_events(
    filter_=SearchEventsRequestFilter(
        workspace_exact="workspaces/0eed0fc7-8a97-4cdf-8c4a-6af571aec864"
    ),
    page_size=50
)
note

Filters don't support aliases. Always use the actual stored UUID values for resources like workspaces and users. For example, use workspaces/0eed0fc7-8a97-4cdf-8c4a-6af571aec864 instead of workspaces/my-workspace-alias, or users/bce09abb-47f8-4e28-8916-91eee0536f3d instead of users/john.doe.

Common Patterns​

Working with timestamps​

Always use UTC timestamps for consistency:

from datetime import datetime, timezone

# Current time
now = datetime.now(timezone.utc)

# Specific time
event_time = datetime(2024, 1, 15, 14, 30, 0, tzinfo=timezone.utc)

Error handling​

Wrap API calls in try-except blocks:

from h2o_audit_trail.exception import CustomApiException

try:
    response = event_client.search_events(
        filter_=SearchEventsRequestFilter(principal_exact="users/john.doe"),
        page_size=50
    )
    print(f"Successfully found {len(response.events)} events")
except CustomApiException as e:
    print(f"Failed to search events: {e}")

Pagination​

To handle large search results with pagination, use this approach:

all_events = []
page_token = ""

while True:
    response = event_client.search_events(
        filter_=SearchEventsRequestFilter(
            start_event_time=datetime.now(timezone.utc).replace(hour=0),
            principal_regex="users/.*"
        ),
        page_size=100,
        page_token=page_token
    )

    all_events.extend(response.events)

    if not response.next_page_token:
        break

    page_token = response.next_page_token

print(f"Retrieved {len(all_events)} events total")

Next steps​

Feedback