Audit Events API
AuditEventCollection reference — get, get_or_none, list, iter, count, one, and first for the project audit log, with time-range and level filters.
AuditEventCollection is accessed via ManagementProject.audit_events. It provides the full collection contract for the project's audit log.
proj = mgmt.project("proj_grating_7f3a")
events = proj.audit_events # AuditEventCollectionThe AuditEvent object
AuditEvent is a frozen dataclass:
Prop
Type
AuditEventCollection.get(audit_event_id)
Fetch a single audit event by ID. Raises if the event does not exist.
Signature
def get(self, audit_event_id: str) -> AuditEvent: ...Parameters
Prop
Type
Returns — AuditEvent.
Side effects — Makes one HTTP read request.
Raises — NotFoundError when no event with audit_event_id exists. AuthenticationError when the API key is invalid or missing.
Example
event = proj.audit_events.get("evt_abc123")
print(event.action, event.level, event.timestamp)AuditEventCollection.get_or_none(audit_event_id)
Fetch a single audit event by ID. Returns None instead of raising when not found.
Signature
def get_or_none(self, audit_event_id: str) -> AuditEvent | None: ...Parameters
Prop
Type
Returns — AuditEvent if found, None otherwise.
Side effects — Makes one HTTP read request.
Raises — AuthenticationError when the API key is invalid or missing.
Example
event = proj.audit_events.get_or_none("evt_maybe")
if event:
print(event.description)AuditEventCollection.list(...)
Return one page of audit events matching the given filters. Default sort is newest first.
Signature
def list(
self,
*,
action: str | None = None,
category: str | None = None,
level: AuditLevel | None = None,
actor_id: str | None = None,
target_type: AuditTargetType | None = None,
request_id: str | None = None,
since: datetime | None = None,
until: datetime | None = None,
limit: int = 100,
cursor: str | None = None,
order_by: AuditOrderBy = "timestamp",
order: Literal["asc", "desc"] = "desc",
) -> Page[AuditEvent]: ...Parameters
Prop
Type
Returns — Page[AuditEvent].
Side effects — Makes one HTTP read request.
Raises — AuthenticationError when the API key is invalid or missing.
Example
from datetime import datetime, timezone
page = proj.audit_events.list(
level="error",
since=datetime(2026, 1, 1, tzinfo=timezone.utc),
limit=50,
)
for event in page.items:
print(event.timestamp, event.action, event.description)AuditEventCollection.iter(...)
Iterate over all audit events matching the given filters across all pages.
Signature
def iter(
self,
*,
action: str | None = None,
category: str | None = None,
level: AuditLevel | None = None,
actor_id: str | None = None,
target_type: AuditTargetType | None = None,
request_id: str | None = None,
since: datetime | None = None,
until: datetime | None = None,
order_by: AuditOrderBy = "timestamp",
order: Literal["asc", "desc"] = "desc",
) -> Iterator[AuditEvent]: ...Parameters
Prop
Type
Returns — Iterator[AuditEvent]: lazy, fetches pages on demand.
Side effects — Makes one HTTP read request per page.
Raises — AuthenticationError on any page fetch.
Example
for event in proj.audit_events.iter(level="error", target_type="workflow_node"):
print(event.timestamp, event.action)AuditEventCollection.count(...)
Return the count of audit events matching the given filters.
Signature
def count(
self,
*,
action: str | None = None,
category: str | None = None,
level: AuditLevel | None = None,
actor_id: str | None = None,
target_type: AuditTargetType | None = None,
request_id: str | None = None,
since: datetime | None = None,
until: datetime | None = None,
) -> int: ...Parameters
Prop
Type
Returns — int.
Side effects — Makes one HTTP read request.
Raises — AuthenticationError when the API key is invalid or missing.
Example
error_count = proj.audit_events.count(level="error")
print(f"{error_count} error-level audit events in this project")AuditEventCollection.one(...)
Return exactly one audit event matching the given filters.
Signature
def one(
self,
*,
action: str | None = None,
category: str | None = None,
level: AuditLevel | None = None,
actor_id: str | None = None,
target_type: AuditTargetType | None = None,
request_id: str | None = None,
since: datetime | None = None,
until: datetime | None = None,
) -> AuditEvent: ...Parameters
Prop
Type
Returns — AuditEvent.
Side effects — Makes one HTTP read request (fetches up to 2 items).
Raises — NotFoundError when no events match. MultipleResultsError when more than one event matches. AuthenticationError when the API key is invalid or missing.
Example
# Useful when you know a request_id produced exactly one event
event = proj.audit_events.one(request_id="req_xyz789")AuditEventCollection.first(...)
Return the first audit event matching the given filters, or None.
Signature
def first(
self,
*,
action: str | None = None,
category: str | None = None,
level: AuditLevel | None = None,
actor_id: str | None = None,
target_type: AuditTargetType | None = None,
request_id: str | None = None,
since: datetime | None = None,
until: datetime | None = None,
) -> AuditEvent | None: ...Parameters
Prop
Type
Returns — AuditEvent (most recent by default sort, i.e. newest first) if found, None otherwise.
Side effects — Makes one HTTP read request (fetches 1 item).
Raises — AuthenticationError when the API key is invalid or missing.
Example
latest_error = proj.audit_events.first(level="error")
if latest_error:
print(latest_error.timestamp, latest_error.description)Time-range filtering
Use since and until with timezone-aware datetime objects. The SDK serializes them to ISO 8601 before sending to the server:
from datetime import datetime, timezone
start = datetime(2026, 5, 1, tzinfo=timezone.utc)
end = datetime(2026, 6, 1, tzinfo=timezone.utc)
for event in proj.audit_events.iter(since=start, until=end, level="warn"):
print(event.timestamp.isoformat(), event.action)Workflow Nodes API
WorkflowNodeCollection and WorkflowNodeLabelCollection reference — get, list, iter, count, one, first for workflow nodes and their labels.
Snapshot API
ManagementProject.snapshot — fetch config, organization, teams, members, workflow nodes, and audit events in a single coordinated call.