Skip to main content
The audit log records every significant action in your organization: project creation, API key generation, member role changes, guardrail updates, and billing changes. Each entry is timestamped and linked to the user or API key that performed the action.

​
Accessing the audit log

Go to Platform → Audit in the sidebar. You need the owner or admin role to view the audit log.

​
What gets logged

Alert rule changes also appear on the Changes timeline as alert_change events. An alert’s webhook URL can contain a secret, so the entry records only whether one is set, never the URL itself.
Actions taken on project-scoped routes (guardrails, prompts, alert rules, annotation queues, and similar) are recorded against your active organization, so they appear in the organization’s audit log alongside organization-level events.

​
Audit entry fields

Each entry contains:

​
Actor types

Every entry is attributed to exactly one of three actor types: If the underlying user or project has since been deleted, the entry still shows the id it was recorded against rather than going blank, so history is never silently erased.
Filter the audit log by a specific actor’s id with the actorId query parameter on GET /v1/orgs/:orgId/audit (and the project-scoped equivalent). It targets the true actor — a user, apiKey (project id), or system row — which is more precise than the legacy userId filter for anything that isn’t a person.
The risk and failure counts at the top of the page come from the whole log for the selected range, not just the page of entries you are looking at.

​
Filtering

Filter audit entries by actor, event type, resource, and date range. Use the event type filter to focus on a specific category — for example, filter by api_key.* to see all key management activity.

​
Exporting

Click Export to download a CSV of the current filtered view. Exports include all fields and are suitable for compliance reviews. The CSV’s columns, in order:
actor_type is appended as the last column rather than placed next to actor, so a script parsing the CSV by column position keeps working unchanged. POST /v1/orgs/:orgId/audit/export (and the project-scoped equivalent) also accepts the same actorId filter described above, in addition to the existing userId filter.

​
Export API

Exports are asynchronous and need the Pro plan or above and the audit:read permission.
1

Request an export

POST /v1/orgs/{orgId}/audit/export or POST /v1/projects/{projectId}/audit/export with format (csv or json), optional filters, and optional maxRecords (up to 10,000, the default). The filters are startDate, endDate, userId, actorId, status, and risk (low, medium, high, or critical; same meaning as on the list view), and the organization route also takes resource. The response is 202 with an exportId and status: "pending".
2

Poll the status

GET /v1/audit/export/{exportId} returns exportId, status, format, recordCount, fileUrl, downloadUrl, storage, error, createdAt, and completedAt.
3

Download the file

Once status is completed, fetch downloadUrl. It is a relative path on the API, signed in with your session or API credentials, and is scoped to the project (/v1/projects/{projectId}/audit/export/{exportId}/download) or the organization (/v1/orgs/{orgId}/audit/export/{exportId}/download) the export was made for. The scope-free GET /v1/audit/export/{exportId}/download works for either.
The download route streams local files (CSV as text/csv, JSON as application/json, as an attachment) and redirects (302) to the stored file for R2. The export must belong to your active organization, and to the project on project routes; otherwise you get 404 Export not found. If the export hasn’t completed you get 409 with the message Export is <status>; no file to download. A completed export’s file is deleted after 30 days (AUDIT_EXPORT_RETENTION_DAYS on a self-hosted deployment, 1 to 365): its status becomes expired and the download answers 409. Request a new export if you need the file again.

​
Integrity and retention

The audit log is append-only: entries can’t be edited or deleted through Zespan, even by organization owners, and the database rejects changes to existing entries. The only deletions are made by audit retention. Audit retention is a single setting for the whole Zespan deployment — it does not follow your plan’s data retention. Automatic deletion of old audit entries is off unless the operator enables it. When it’s enabled, entries older than the retention period (90 days by default) are removed, except critical security events, which are never removed by retention:
  • Role changes and member removals
  • Organization deletion
  • Billing subscription and payment events
  • API key creation and rotation
  • ZespanPilot actions
  • Denied authorization attempts
  • Any entry recorded at critical risk
If you need a longer audit history for an audit or investigation, export it with Export as CSV and keep the file in your own records.
On a self-hosted deployment, the operator controls this with AUDIT_RETENTION_DELETE_ENABLED and AUDIT_RETENTION_DAYS. See Environment variables.

​
Automated export

For continuous compliance logging, set up a webhook that fires on audit events. See Webhooks for configuration.

​
Evidence packs build on this log

Membership and role-change entries from this log are what back the CC6.1 access-control section of a generated control evidence document, and guardrail/prompt/agent-lifecycle entries back its change-management (CC8.1) section. See Evidence Packs to generate an audit-ready document instead of exporting this log by hand.

​
Next steps

  • Security — data handling, encryption, and access controls
  • Organizations — team member roles and permissions
  • Evidence Packs — generate audit-ready documents from this log and other recorded platform data