Skip to main content

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 the lifespan 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 and dead_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 to api.fact0.io during unit tests. Mock the transport or the client using this fixture: