Audit client
Constructor options
Environment variable:
FACT0_API_KEY (optional if api_key is passed). Override the API origin with the base_url parameter.
Write methods
log(**fields) -> None
Validate and enqueue one event. Returns immediately.
log_batch(events: list[dict]) -> BatchResult | AsyncReceipt
Send up to 1000 events. Uses batch endpoint.
flush() -> None
Block until the in-memory buffer is drained.
close() -> None
Stop background flusher and drain. Registered with atexit.
Read methods
get_event(event_id: str) -> dict
GET /v1/events/{id}
list_events(**filters) -> dict
GET /v1/events - filters: actor_id, actor_type, action, resource_id, outcome, from, to, page, page_size.
get_receipt(receipt_id: str) -> dict
GET /v1/receipts/{id}
wait_for_receipt(receipt_id: str, timeout_s=30) -> dict
Poll until status is committed or failed.
Verify methods
verify(from_=None, to=None, scan_all=False) -> dict
GET /v1/verify
verify_event(event_id: str) -> dict
GET /v1/events/{id}/verify
Export methods
export_pdf(from_=None, to=None) -> bytes
GET /v1/export/pdf
export_evidence_pack(from_=None, to=None) -> bytes
GET /v1/export/evidence-pack
Stream
stream_events() -> Iterator[dict]
SSE iterator over GET /v1/events/stream.
Error handling
By default transport errors are logged and optionally written to dead-letter JSONL.
Production Integration Recipes
1. Production FastAPI lifespan Hook
Always configure thelifespan hook to ensure the background batching workers are safely stopped and buffers are drained when the application shuts down.
2. Dead-Letter Queue (DLQ) Recovery & Replay
If a network partition occurs anddead_letter_path is configured, Fact0 writes unsent events as JSONL rows to the specified file. Use this script to replay and re-submit them to the API once connectivity is restored:
3. Unit Testing & Mocking in pytest
Do not send live HTTP requests toapi.fact0.io during unit tests. Mock the transport or the client using this fixture: