Reporting & Audit

As an Auditor or Manager, you can view audit logs, track usage and spending, verify data integrity, and generate compliance reports. This guide covers how to access audit logs, understand what gets audited, export data for analysis, and meet regulatory requirements.

Audit & Reporting

View Audit Logs

Access audit events, filter by type and time, and review activity history.

View logs →

Track Usage & Spending

Monitor team spending, view usage reports, and analyze costs by model and project.

Track usage →

Verify Integrity

Download audit proofs and verify tamper-evident chains locally.

Verify data →

Export & Compliance

Export audit archives and meet regulatory requirements for your organization.

Export data →

---

Who Can Access Audit Logs

Audit logs are only accessible to users with the Auditor or Manager role. These roles provide read-only access to audit events for compliance, security investigations, and accountability.

Auditor: Read-only access to all audit logs for their organization, including complete historical data. Auditors can view events, download proofs, and export archives. They cannot modify settings, manage users, or create API keys. The Auditor role is designed for compliance officers, security analysts, and reporting staff who need visibility into system activity without administrative permissions.

Manager: Full administrative control plus audit access. Managers can view audit logs, manage team members, configure budgets, and access all organizational data. Managers have the same audit access as Auditors, plus the ability to change settings and manage users.

Important: When you promote someone to Auditor, they immediately gain access to all historical audit data for their organization. This includes past security incidents, terminated employees’ actions, compliance investigations, and organizational activity since deployment. For more details on role permissions, see Managing Teams: Understanding Roles.

Why it matters

Restricting audit access to Auditors and Managers ensures that sensitive compliance data is only visible to authorized personnel. This separation of duties supports regulatory requirements and reduces insider threat risks.

What Gets Audited

Nexus creates audit events for every significant action in the system. Audit logs are separate from usage analytics and are designed specifically for compliance, accountability, and security investigations.

Core Audit Event Types

AI Request Events: Every AI request through Nexus generates a gateway.request.completed event with request ID, model used, token counts, costs, classification level, and completion status. These events provide a complete record of all AI interactions for compliance and billing reconciliation.

Policy Decisions: Every policy evaluation creates a policy.decision event with the effect (allow/deny), obligations applied, and reason codes. Policy events show when requests were blocked, why they were denied, and what security controls were enforced.

Authentication & Access: Login attempts, identity federation, and session creation are audited with events like auth.oidc.login_started, login_succeeded, and login_denied. These events track who accessed the system, when, and whether authentication succeeded or failed.

User & Team Management: Creating users (user.created), disabling accounts (user.disabled), and modifying team memberships generate audit events. These events preserve the history of access control changes for compliance reviews.

Resource Management: Creating or modifying organizations, projects, and provider keys generates audit events (org.created, project.created, providerkey.created). These events track configuration changes and resource provisioning.

Wallet & Billing: All financial transactions generate audit events including wallet.topup.succeeded, wallet.refund.created, and wallet.reconciliation.mismatch. These events support financial audits and detect billing discrepancies.

Audit Access: Viewing audit logs itself creates data_access.audit_viewed events with the view type (list/detail/proof) and which events were accessed. This recursive auditing creates an accountability trail for who reviewed compliance data.

Event Schema

Every audit event includes a standardized set of fields that provide complete context for compliance and security investigations. Each event has a unique ULID identifier (Event ID) for precise tracking and reference, along with a nanosecond-precision UTC timestamp that ensures accurate chronological ordering even in high-throughput environments. The Tenant ID scopes the event to a specific organization for multi-tenant isolation, preventing cross-contamination of audit data between different customers or business units. The Kind field specifies the event type (such as gateway.request.completed or policy.decision) to enable filtering and analysis by activity category. Actor information captures who performed the action, whether it was a specific user, a service account, the CLI tool, or the system itself acting autonomously. The Subject field identifies what resource was affected by the action, such as a request, session, project, or user account. Classification indicates the data sensitivity level for the event itself, ensuring that audit logs respect the same security boundaries as the data they describe. Event-specific attributes provide additional details that vary by event type, such as token counts for AI requests or denial reasons for policy decisions. Finally, the Causation ID links related events together in a workflow, allowing investigators to trace a complete chain of activity from initial request through all downstream effects.

For the complete event schema and all event types, see the Audit Event Reference.

Why it matters

Comprehensive auditing ensures you have a complete record of system activity for compliance investigations, security incident response, and accountability. Every action leaves a trail.

Viewing Audit Logs

Audit logs are accessible through the Nexus console and API. You can filter events by type, classification level, time range, and other criteria to find specific activity.

Accessing the Console

To view audit logs in the console, navigate to your organization or workspace audit page using the URL patterns /o/<org-slug>/audit for organization-level audit access or /w/<workspace-slug>/audit for workspace-level access. Once there, use the available filters to narrow down the events you’re investigating: filter by event kind to focus on specific event types like login attempts or AI requests, by classification level to show only events at particular sensitivity levels, or by time range to view activity from a specific date range. Click any event in the list to open the event drawer and see complete details, including the ability to download inclusion proofs for sealed events that have been cryptographically batched and signed.

The console provides a user-friendly interface for browsing audit history without requiring API knowledge or command-line tools.

Using the API

For programmatic access or integration with external tools, use the audit API:

# List audit events (requires bearer token with audit:read scope)
curl -H "Authorization: Bearer your-token" \
  https://your-nexus.example.com/api/audit/events

# Get a specific event
curl -H "Authorization: Bearer your-token" \
  https://your-nexus.example.com/api/audit/events/<event-id>

# Download inclusion proof for verification
curl -H "Authorization: Bearer your-token" \
  https://your-nexus.example.com/api/audit/events/<event-id>/proof

API responses are JSON and support pagination for large result sets. Results are automatically filtered to events within your authorized organization scope.

Understanding Event Details

When you view an event in the console or retrieve it via API, you see comprehensive information organized into several categories. Core metadata includes the Event ID, timestamp, tenant identifier, and classification level. Actor information reveals who performed the action, showing user email addresses, service names, or system identifiers. Subject details identify what resource was affected by the action. Event-specific attributes provide contextual information that varies by event type, such as token counts and costs for AI requests, or denial reasons and obligations for policy decisions. For sealed events that have been batched and cryptographically signed, you also see batch information including the Merkle root, batch sequence number, and Ed25519 signature, along with the ability to download an inclusion proof that provides cryptographic verification of the event’s integrity for offline validation.

Events are immutable once batched. You cannot modify or delete audit events, ensuring tamper-evident compliance records.

Why it matters

Easy access to audit logs through both console and API means compliance teams can review activity without technical barriers, while security engineers can integrate audit data into SIEM tools and automated workflows.

Understanding Tamper-Evident Audit

Nexus audit logs are tamper-evident, meaning any modification or deletion of audit data is cryptographically detectable. This provides stronger guarantees than traditional “append-only” logs and meets regulatory requirements for data integrity.

How Tamper-Evident Auditing Works

Nexus uses a per-tenant Merkle chain architecture that provides cryptographic guarantees of audit log integrity through a multi-stage process. First, audit events are collected and periodically batched, typically every few minutes, grouping related events together for efficient processing. Each batch of events is then hashed into a binary Merkle tree using the BLAKE3 cryptographic hash function, creating a hierarchical structure where each parent node represents the hash of its children, ultimately producing a single Merkle root that cryptographically represents the entire batch. This Merkle root is signed with Ed25519, a modern elliptic curve signature algorithm, and linked to the previous batch’s root, creating an unbroken chain where each batch cryptographically commits to all preceding batches. The signed batches are written to WORM (Write-Once-Read-Many) object storage with Object Lock enabled, ensuring that archived data cannot be modified or deleted until the retention period expires. Finally, anyone with access to the batch archives can download them and verify the cryptographic chain offline using verification tools, without needing to trust the live Nexus database.

This architecture ensures tamper detection by making any modification to an event change its hash, which breaks the Merkle chain and becomes immediately detectable during verification. It provides non-repudiation through Ed25519 signatures that cryptographically prove each batch was sealed by the legitimate audit service and has not been forged. The offline verification capability allows auditors and compliance teams to independently validate audit integrity without relying on the system being audited, a critical property for regulatory compliance. This design meets stringent requirements for HIPAA audit controls, SOC 2 trust services criteria, FedRAMP AU-9 (protection of audit information), and NIST SP 800-53 controls for federal systems.

What “Tamper-Evident” Means

Tamper-evident does not mean data cannot be modified—it means modifications are detectable through cryptographic proof. If someone with database access attempts to alter or delete an audit event after it has been batched and sealed, several cryptographic properties immediately reveal the tampering: the event’s canonical hash will no longer match the stored hash in the Merkle tree, the Merkle chain will break when verification tools recompute the tree root, the signed batch envelope will no longer validate against the stored Ed25519 signature, and verification tools will detect and report the inconsistency. This provides cryptographic proof of integrity, which is fundamentally stronger than access controls alone, because even a privileged attacker with full database access cannot modify sealed audit data without leaving detectable evidence. The tamper-evident property transforms audit logs from “data protected by access controls” into “data protected by mathematics,” providing the level of assurance required for regulatory compliance and legal proceedings.

Sealed vs Unsealed Events

Unsealed events: Recently created events that have not yet been batched. These exist only in the hot Postgres database and are not yet tamper-evident. Unsealed events can theoretically be modified by someone with direct database access (though database triggers attempt to prevent this).

Sealed events: Events that have been batched, hashed into a Merkle tree, signed, and archived to WORM storage. Sealed events are fully tamper-evident. Any modification is cryptographically detectable through verification.

Risk window: The time between event creation and sealing (typically minutes) is when events are weakest. Once sealed, events gain cryptographic protection. For high-security environments, configure shorter batch intervals to minimize this window.

For technical details on the architecture, see Tamper-Evident Audit (ADR-0007).

Why it matters

Tamper-evident auditing provides cryptographic proof of data integrity for regulators, auditors, and security investigations. You can prove that audit records have not been altered, which is critical for compliance and legal proceedings.

Verifying Audit Integrity

You can verify audit integrity at any time by downloading batch archives and running the verification tool. This proves that audit data has not been tampered with since it was sealed.

Downloading Inclusion Proofs

For individual events, download an inclusion proof from the console or API by navigating to a sealed event in the console interface, clicking the “Download Inclusion Proof” button in the event details drawer, and saving the resulting JSON file. The inclusion proof contains the original event data, the batch metadata (including Merkle root, Ed25519 signature, and batch sequence number), the Merkle path showing how the event hashes up to the batch root, and the meta-root that links this batch to the broader chain. You can verify this proof manually using cryptographic tools or with the automated verification tool described below.

Verifying Archive Integrity

For complete verification of your audit archive, start by contacting your platform administrator to export audit archives from object storage (archives are stored in S3-compatible storage like Amazon S3 or MinIO with Object Lock enabled to prevent modification). Next, build the verifier tool by cloning the Nexus repository from GitLab (git clone https://gitlab.com/vortexaq/nexus.git), navigating into the directory, and running cargo build --release -p nexus-audit --bin nexus-audit-verify to compile the verification binary. Finally, run verification with ./target/release/nexus-audit-verify verify --archive-path ./path-to-archive, which will output the total batches verified, any integrity failures detected, signature validation results, and chain continuity check outcomes.

The verifier performs a comprehensive cryptographic validation of the entire audit trail. First, it re-encodes each event using the canonical encoding and verifies that the computed hash matches the stored hash, ensuring no event has been tampered with. Next, it rebuilds the Merkle tree from these event hashes and confirms that the computed root matches the signed root in each batch, validating the integrity of the batch structure. The verifier then validates all Ed25519 signatures against the stored public keys, proving that each batch was sealed by an authorized signer. To ensure chain continuity, it verifies that each batch cryptographically links to the previous batch’s root, creating an unbroken chain of custody. Finally, it checks meta-root consistency across batches, validating the cross-batch linkage that ties the entire audit log together.

If verification passes, you have cryptographic proof that the audit data is intact and unmodified since sealing.

What to Do if Verification Fails

If the verifier detects tampering or integrity failures, follow a strict incident response protocol: preserve the archive as evidence without deleting or modifying it, notify your security team immediately as this represents a potential security incident or insider threat, isolate the affected system to prevent further modifications while the investigation proceeds, review the failure details output by the verifier to understand which batch or event failed and the specific nature of the failure, and follow your organization’s incident response plan by treating this as a potential breach requiring full investigation and remediation.

For detailed guidance, see Runbook: Audit Verifier Failure.

Why it matters

Offline verification means you can prove audit integrity to regulators, auditors, and security investigators without relying on the live Nexus system. Even if the entire Nexus deployment is compromised, you can verify historical audit data from backups.

Exporting Audit Data

You can export audit data for long-term archival, compliance reporting, or analysis in external tools. Nexus supports both API-based exports and full archive exports.

API Export

Use the audit API to export events as JSON:

# Export events in a date range
curl -H "Authorization: Bearer your-token" \
  "https://your-nexus.example.com/api/audit/events?from=2026-01-01&to=2026-01-31" \
  > audit-january-2026.json

API exports are particularly convenient for operational and analytical use cases. They enable seamless importing into SIEM tools like Splunk, Elastic, and Datadog for real-time monitoring and alerting. Teams can generate custom compliance reports tailored to their specific regulatory requirements, analyze particular event types or time periods for security investigations, and integrate audit data into automated workflows for incident response or governance processes.

It’s important to note that API exports include event metadata and attributes but do not include Merkle proofs or batch signatures. For cryptographic verification, use archive exports (see below).

Archive Export

For complete audit archives with cryptographic proofs:

1. Contact your platform administrator to export archives from object storage

2. Archives include:

   • All batched audit events in NDJSON format (compressed with Zstandard)
   • Signed Merkle batch roots
   • Meta-roots linking batches together
   • Ed25519 public keys for signature verification

3. Storage requirements: Archive size depends on event volume. A typical deployment generates 100-500 MB of compressed audit data per million requests.

Archive exports support:

• Long-term retention for compliance (7-10 years for regulated industries)
• Offline verification (see Verifying Audit Integrity)
• Legal discovery and regulatory audits
• Disaster recovery and backup restoration

Retention Requirements

Your organization’s retention policy depends on regulatory requirements and industry standards. Different frameworks impose varying retention periods based on the sensitivity of data processed and the compliance regime:

• HIPAA (healthcare): 6 years minimum from the date of creation or last use, whichever is later. This applies to covered entities and business associates handling protected health information (PHI). Some states mandate longer retention periods (up to 10 years), so verify your specific jurisdiction.

• SOC 2: Typically 1-3 years depending on the attestation period and audit requirements. Service organizations should retain audit logs for at least one full audit cycle plus the examination period. Many organizations retain 3 years to support continuous monitoring and year-over-year comparisons.

• PCI-DSS (payment card): 1 year minimum with immediate availability, 3 years recommended for comprehensive security analysis. Requirement 10.7 mandates that audit trail history must be retained for at least one year, with a minimum of three months immediately available for analysis.

• GDPR (EU): No fixed minimum retention period, but data must be kept only as long as necessary for the purposes for which it is processed. Article 5(1)(e) requires storage limitation. Organizations must document their retention rationale and implement automated deletion when the retention period expires. Audit logs related to data subject rights (access, deletion, portability) should be retained to demonstrate compliance.

• FedRAMP (US government): 1 year minimum for moderate and high impact systems as per NIST SP 800-53 AU-11. High-impact systems often require 3 years or longer based on agency-specific requirements. Archives must be maintained in a tamper-evident format with cryptographic integrity protection.

• CCPA/CPRA (California): While not explicitly specifying audit log retention, businesses must maintain records of consumer requests and responses for at least 24 months to demonstrate compliance with consumer privacy rights.

• ISO 27001: No specific retention period mandated, but organizations must define and document retention periods in their Information Security Management System (ISMS). Most certified organizations retain audit logs for 1-2 years minimum to support annual audits and incident investigations.

Your platform administrator configures retention policies at the deployment level. Archives stored in WORM (Write-Once-Read-Many) storage cannot be modified or deleted until the retention period expires, ensuring immutability for compliance purposes. When planning retention:

• Consider the longest applicable requirement: If multiple regulations apply, use the longest retention period to ensure comprehensive compliance.
• Factor in legal holds: Litigation or investigations may require preserving data beyond standard retention periods.
• Plan for storage costs: Audit archives compressed with Zstandard typically consume 100-500 MB per million requests. Calculate your expected volume and budget accordingly.
• Document your policy: Clearly document your retention rationale, especially for GDPR compliance where you must justify retention periods.
• Automate expiration: Configure automated deletion after retention periods expire to minimize storage costs and reduce data exposure risk.

Why it matters

Export capabilities ensure you can meet regulatory retention requirements, provide audit data for legal proceedings, and preserve compliance records even if you migrate away from Nexus in the future.

Usage Reports and Spending

In addition to audit logs, Nexus provides usage reports and spending analytics that give operational teams visibility into costs, consumption patterns, and resource allocation. These reports serve a fundamentally different purpose than audit logs: while audit logs provide tamper-evident compliance records for security and regulatory requirements, usage reports are mutable analytical data optimized for financial planning, budget management, and operational decision-making. Usage data is stored in ClickHouse for fast aggregation and can be recalculated or corrected for billing adjustments, whereas audit logs are immutable once sealed. Organizations typically use audit logs to answer “who did what and when” for compliance investigations, while usage reports answer “how much did we spend and where” for cost optimization and forecasting.

Viewing Usage in the Console

The console usage dashboard provides comprehensive visibility into spending patterns and resource consumption. You can view spending over time with daily, weekly, and monthly spending trends that help identify usage spikes and budget variance. The dashboard breaks down costs by model to show which AI models are consuming the most budget, enabling you to optimize model selection for cost efficiency. It also shows costs by project to identify which applications or teams are driving spending, supporting chargeback and budget allocation decisions. Token usage metrics display total tokens processed along with token-level cost breakdowns, providing granular insight into consumption patterns. Finally, request volume data shows the number of requests processed by each model and provider, helping you understand traffic patterns and identify potential optimization opportunities.

Usage data is stored in ClickHouse (a columnar analytics database) and is optimized for fast queries and aggregations. Unlike audit logs, usage data is mutable and can be recalculated for billing corrections.

Exporting Usage Data

Export usage data for financial reconciliation or analysis:

# Export wallet transactions as CSV
curl -H "Authorization: Bearer your-token" \
  "https://your-nexus.example.com/api/billing/wallet/transactions/export.csv" \
  > wallet-transactions.csv

CSV exports include comprehensive transaction details: transaction ID and timestamp for precise tracking, transaction amount in platform currency, transaction type (such as topup, refund, escrow, or commitment) to categorize the financial activity, project and organization attribution showing where costs were incurred, and causation IDs that link wallet transactions back to the corresponding audit events for complete traceability between financial and compliance records.

Difference Between Audit Logs and Usage Reports

Audit logs serve compliance, accountability, and security purposes by providing an immutable, tamper-evident record of system activity. Once sealed with cryptographic proofs, audit logs cannot be modified, ensuring that policy decisions, access events, and system actions remain trustworthy for regulators, auditors, and security teams investigating incidents or demonstrating compliance. In contrast, usage reports are designed for operations, billing, and visibility, offering mutable data that can be corrected for billing errors or recalculated as needed. These reports are optimized for fast queries and aggregations, focusing on costs, token usage, and request volume to help managers, finance teams, and users understand consumption patterns and optimize spending.

Both systems are important but serve fundamentally different purposes. For regulatory compliance, security investigations, and demonstrating accountability to auditors, always rely on audit logs with their cryptographic guarantees. For billing reconciliation, cost analysis, budget forecasting, and operational dashboards, use usage reports with their flexible analytical capabilities.

Why it matters

Separating audit logs from usage analytics ensures compliance data remains tamper-evident while allowing operational data to be flexible and queryable. You get both accountability and visibility.

Compliance and Regulatory Requirements

Nexus is designed to meet compliance requirements for regulated industries including healthcare, finance, government, and critical infrastructure.

Supported Regulations

Nexus audit and reporting capabilities are designed to satisfy specific controls and requirements across major compliance frameworks. The table below maps each regulation to the technical controls Nexus implements:

Regulation	Control/Requirement	Nexus Implementation
HIPAA (Health Insurance Portability and Accountability Act)	Audit controls (45 CFR 164.312(b))	Complete audit trail of PHI access with immutable event logging
	Integrity controls (45 CFR 164.312(c)(1))	Tamper-evident audit with cryptographic verification using Merkle trees and Ed25519 signatures
	Transmission security (45 CFR 164.312(e)(1))	TLS encryption for all API communications and data in transit
SOC 2 (Trust Services Criteria)	CC7.2 (Monitoring)	Comprehensive audit logging and alerting for system events and access
	CC7.3 (Evaluation)	Audit log review capabilities and anomaly detection through structured event analysis
	CC8.1 (Change management)	Complete audit trail of configuration changes with before/after snapshots
GDPR (General Data Protection Regulation)	Article 32 (Security)	Technical and organizational measures including audit logging and integrity controls
	Article 5(2) (Accountability)	Demonstrable compliance through audit evidence and verifiable integrity proofs
	Article 17 (Right to erasure)	Classification-based redaction in audit logs to protect data subject privacy
FedRAMP (Federal Risk and Authorization Management Program)	AU-2 (Audit Events)	Canonical event production with tenant-scoped ingestion and comprehensive event coverage
	AU-9 (Protection of Audit Information)	Merkle roots, Ed25519 signatures, and mutation-rejecting database triggers
	AU-10 (Non-repudiation)	Signed batch envelopes with cryptographic verification via CLI verifier tool
	AU-11 (Audit Retention)	WORM (Write-Once-Read-Many) archive storage with configurable retention policies
PCI-DSS (Payment Card Industry Data Security Standard)	Requirement 10	Comprehensive audit logging of all access to cardholder data environments
	Requirement 10.5	Audit trail protection with integrity verification and tamper-evident storage

For detailed control mappings, including specific evidence artifacts and attestation guidance, see the Compliance Map.

Classification-Based Redaction

Nexus automatically redacts sensitive data in audit logs based on classification level to balance compliance visibility with data protection. Email addresses are redacted by transforming entries like user@example.com into ***@***, preventing exposure of personal identifiers while maintaining the record that an email-based action occurred. IP addresses are similarly masked, changing 192.168.1.100 into ***.***.***.*** to protect network topology information while preserving the fact that a network-based event took place. API keys are stored as prefixes only, showing nxs_abc... instead of the full key value, allowing investigators to identify which credential was used without compromising its security. This classification-based redaction ensures that audit logs can be reviewed by compliance staff who need visibility into system activity without exposing sensitive production data that could create additional security or privacy risks. The original unredacted data remains in the live system for operational use by authorized personnel, but audit logs maintain privacy-preserving representations.

Audit Retention and Deletion

Nexus does not support deleting individual audit events. This is intentional to preserve compliance records. Audit events are retained according to your deployment’s retention policy (configured by your platform administrator).

User accounts cannot be deleted, only disabled. This ensures audit events always reference valid user IDs. If you need to anonymize user data for GDPR compliance, contact your platform administrator to discuss pseudonymization strategies that preserve audit integrity while meeting privacy requirements.

Why it matters

Meeting regulatory requirements is not optional for many organizations. Nexus provides the technical controls and audit evidence needed to pass compliance audits and demonstrate due diligence.

---

Next Steps

Now that you understand audit logs and reporting, you might want to explore:

Managing Teams & Access

Learn how to assign Auditor roles, manage permissions, and control who can view audit logs.

Manage access →

Threat Model

Review the security analysis of audit log protection, including tamper resistance and access controls.

Security analysis →

Compliance Map

See detailed mappings between Nexus controls and regulatory requirements (NIST, SOC 2, HIPAA, etc.).

Compliance details →