Audit ledger export

Your audit ledger is a continuous record of what happened in your workspace. The export hands you those rows as CSV or NDJSON.

Pulling an export

Admin or owner only, and today a role reaches Trefur only from a signed-in session. In the dashboard that is Reports → Audit log → Audit trail, where Export CSV and Export NDJSON each download one page.

A workspace API key cannot pull this export. The /v1 surface accepts API keys and only API keys, and an API key carries scopes, never a role — so a key-authenticated caller arrives as a viewer and is refused with 403. Every class of key behaves the same way, and no scope changes it. A scheduled archival job running on a key is not something you can build yet; an admin or owner pulling from a signed-in session is.

The parameters the export takes:

Only the first page of a pull is recorded in the ledger — the continuations belong to the same pull. The time range is carried inside the cursor, so a continuation cannot be steered outside the pull it started: passing a different start_time with an after cursor does nothing.

The request behind the dashboard's buttons is the one below. Use it if you are scripting the pull with a signed-in session — to follow the cursor past the first page, which the buttons do not do.

GET /api/observe/governance/ledger/export
      ?format=ndjson
      &start_time=2026-09-01T00:00:00Z
      &limit=50000

Origin:        your dashboard (app.trefur.com)
Authorization: the signed-in session's bearer token

What a row contains

NDJSON gives one object per line; CSV gives a header row and one line per entry. Each row carries its sequence number, event type, severity, summary, agent, actor type and id, API key id, timestamp, workspace and redaction time, together with the integrity fields that let the record be checked.

Limits

• The dashboard's export buttons download the first page of a pull. Follow the cursor to fetch the rest.
• Admins and owners pull this export from a signed-in session. Workspace API keys carry scopes, not roles, so scheduled archival on a key is not yet available.
• The export reads the ledger as it stands: entries outside your workspace's retention window are gone, and redacted text stays redacted.

See also: the OCSF export for activity and findings in a SIEM-native schema.