> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit and replay

> The append-only audit trail — what it records, how to query it, pull a run's audit packet, and where authorization denials land.

Last updated 2026-11-11

·
applies to 2026-09-29

·
main

This page is for operators answering compliance, forensics, or post-incident questions. Forge keeps an **append-only audit trail**. Every governance decision, lifecycle transition, configuration change, and agent execution event is recorded with full actor attribution. **No mutation paths can update or delete records.** The only deletion path is the daily retention sweep at the configured TTL.

Two questions come up most, and each has one call: what happened in one run ([its audit packet](#pull-a-run’s-audit-packet)), and what happened across the deployment in a window ([a compliance export](#compliance-exports-over-the-platform-api)).

For the live operator surfaces (Watchtower / Events / InterventionCenter), see [Observability](https://docs.gloo.com/forge/run/observability.md). For the gate-by-gate provenance, see [Trust Fabric in production](https://docs.gloo.com/forge/run/trust-fabric.md).

When to reach for something else

If you are debugging in real time, use the **Events** view in Observe — it shows the same data with sub-second latency. Audit is for the after-the-fact question, when you need a tamper-evident record. If you need to inspect a specific run's full execution (conversation log, tool calls, agent reasoning), use the **Traces** view — audit shows lifecycle events, traces show step-level mechanics.

***

## Pull a run's audit packet

A run's audit packet answers, in one read, what happened in the run and why governance passed, held or blocked it. It is a summary built for review and export, not every row: it carries counts, the latest decision, and the run's 15 most recent key events. The calls use the `FORGE_BASE` and `ACCESS_TOKEN` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md).

**1. Find the run**

If you kept `data.runId` from the dispatch response, skip this step. Otherwise list the workflow's recent runs, newest first:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/runs?workflowId=$WORKFLOW_ID&limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {id, status, startedAt}'
```

This needs `runs:read`. A page can be short while `meta.hasMore` is true; follow `meta.nextCursor` to read on.

**2. Read the packet**

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/runs/$RUN_ID/audit-packet" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data | {disposition, approvals: (.approvals | {total, pending, approved, rejected}), headline: .explanation.headline, actions}'
```

This needs `workflows:read` where the run lives, and it refuses an External App token: send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential) or a platform API key as the bearer. A credential that holds it nowhere gets a recorded `403`; one that holds it only elsewhere gets a recorded `404`, the same answer as a run that does not exist.

**3. Read it top to bottom**

| Field | What it tells you |
| - | - |
| `run` | The run's ID, type, status, operator status, workflow, goal, start and completion times, and duration. |
| `disposition` | The run status, the operator status, the governance disposition (`pass`, `hold`, `block`, or `none`) and a summary code: `approval_required`, `succeeded`, `blocked`, `failed`, `cancelled` or `in_progress`. |
| `approvals` | How many approvals were requested, pending, approved and rejected, the oldest pending age, and each pending item with its step and age. |
| `governance` | Decision counts by disposition. The latest decision names its blocking gate, the policy that held it, every failed gate, and the trust and budget snapshots it was decided on. Policy and gate signals follow, then context eligibility: where the run's context came from and how far it may act (`summarize_ok`, `recommend_ok`, `approval_only` or `autonomous_blocked`). |
| `timeline` | Event totals by source (audit, platform, operator notes), and up to 15 key events, newest first. `redactedForBudget` counts knowledge events whose case text was withheld because reading it would pass the read size limit. |
| `explanation` | A headline and the rationale behind it. |
| `actions` | Recommended next steps, each with a reason, a priority (`high`, `medium` or `low`) and, when there is one, a link. |

Over MCP, `forge_call_read_operation` reads the same packet. It is in the default `start` job, so no job selection is needed:

```json theme={null}
{ "operationId": "getRunAuditPacketAdmin", "input": { "runId": "<run id>" } }
```

For every audit row of a period rather than one run's summary, use a [compliance export](#compliance-exports-over-the-platform-api).

***

## Event structure — what every row carries

This is the shape of each record a [compliance export](#compliance-exports-over-the-platform-api) returns, alongside a stable `id`. Only **two fields are required** — `event` and `timestamp`. Everything else is optional, so treat any other field as "present when the emitter had it", not as guaranteed:

| Field | Required | Description |
| - | - | - |
| `event` | yes | Specific event slug — e.g. `workflow.started`, `agent.created`, `governance.approval_requested` |
| `timestamp` | yes | Epoch milliseconds |
| `category` | no | One of the 23 audit categories (validated by the root audit writer) |
| `resourceType` | no | One of the 32 audit resource types (validated by the root audit writer and component schema) |
| `resourceId` | no | Opaque identifier for the affected entity |
| `actor` | no | Display string for the user or agent that triggered the event |
| `actorType` | no | `human`, `agent`, `system`, or `delegated_agent` |
| `actorIdentity` | no | Full `ActorIdentityV1` shape (flexible document) when available |
| `runId` / `stepId` / `interfaceId` | no | Cross-references tying the event to a workflow run, specific step, or interface call |
| `detail` | no | Event-specific structured payload |

The functions that take an actor argument record their authenticated caller instead: the uploader of a workflow document, the creator of a tool, skill, agent or step, the author of a scheduled org change, the actor of a bridge audit event, and who granted or revoked a worker's raw-bash grant. The argument (`uploadedBy`, `createdBy`, `authorId`, `actor`, `grantedBy` or `revokedBy`) is accepted so existing callers keep working, and is ignored.

The `resourceType` values, in schema order, are `agent`, `skill`, `model`, `gateway`, `deployment`, `document`, `workflow`, `project`, `worker_role`, `policy`, `ai_generation`, `codebase`, `run`, `step`, `position`, `evaluationRun`, `tool`, `factory`, `budget`, `platform`, `chatDraft`, `worker`, `provider`, `capability`, `procedure`, `pod`, `credential`, `secret`, `knowledge_entry`, `knowledge_export`, `workflowTriggers`, and `file`.

A `workflowTriggers` event identifies the Capability URL ingress trigger for an accepted or rejected workflow request. Its `resourceId` is the trigger ID; the audit detail records the outcome and status code, without the request body.

A `knowledge_entry` event is shown only to a reader who can read the knowledge namespace it names. A `knowledge_export` event, a refused knowledge export, is not fenced that way, so every audit reader sees who asked to export which namespace and why it was refused. It never carries knowledge content.

A `file` event records one allowed read of a stored file: a download link, text, bytes, a copy into a sandbox, or a copy into platform data. It is written before the link or any byte leaves. That covers reads through the API's file content and inference routes, a procedure, a workflow agent, a chat or builder session, a Console download, and ingestion. Ingestion means adding a file to knowledge and importing an org chart; it records `mode: "ingest"` and names the person or app that asked for it. A read whose event cannot be written is refused. Its `resourceId` is the file ID (a stored blob with no file row is named by its storage ID), `actor` names the reader (Observe › Run history shows it in words: a person, app, agent or API key by name, a procedure or chat session as such, never its id), and `detail` holds the surface, the mode and a reference (a request, invocation, session, chat message, run or attempt ID). It never carries the file name or content.

Some reads write no `file` event, by design: a run's output delivered to its declared destination, avatars, and generated exports.

***

## Audit categories

The canonical list has 23 categories. The root audit writer validates `category` against it before writing through the `forge-governance` component. The component's category column is a string, but its category list mirrors the root list and its `resourceType` column validates against the component's resource-type enum. Contract tests require both lists to stay in parity.

| Category | Typical events |
| - | - |
| governance | Trust Fabric decisions, approval requests / resolutions, policy lookups, qualified approval releases and self-releases |
| safety\_gate | Preflight / safety / budget / guardrails / autonomy gate outcomes |
| `workflow` | Run lifecycle (`workflow.started`, `workflow.completed`, `workflow.failed`, `workflow.cancelled`) and step dispatch |
| `agent_exec` | Agent turns: `agent.dispatched`, `agent.completed`, `agent.failed`, tool-call outcomes |
| `lifecycle` | Workforce / lifecycle state transitions (hire, suspend, dismiss, role change) |
| `registry` | Catalog mutations — agents, skills, models, gateways, tools, worker roles |
| `deployment` | Deployment create / activate / deactivate / rollback |
| `system` | Cron runs, retention sweeps, seed / backfill mutations, operator-initiated admin actions |
| `codebase` | Sandbox / factory codebase changes — snapshots, commits, artifact writes |
| `ai_generation` | LLM-generated content actions (approvals, diffs, evals), gateway key rotations |
| `routing` | Gateway routing decisions, fallback selections, vendor swaps |
| `evaluation` | Evaluation run creation, scoring, publication |
| `dispatch` | Non-workflow dispatch composition (chat, factory, copilot, workflowArchitect) that opts in via `dispatchSite` |
| `ops_kill_switch` | Operator emergency interventions — pause / resume / terminate agent, pause / disable gateway, pause / archive factory, freeze budget, global platform kill |
| `ops` | Operator notes and attention-item acknowledgments, written with the note or acknowledgment |
| `config` | Provider config mutations (`setProviderConfig`, `enableProvider`, `disableProvider`) |
| `credentials` | Credential lookups at agent invocation time (`credentials.resolved`, `credentials.denied`) |
| `governance_posture` | Changes to the publish judge advisory setting (`workflow_publish_judge_gate`), one row per write. Distinct from `governance`, which is policy and permission events |
| `governance_door_switch` | Door-switch writes: one `governance_door_switch_changed` row per stop, resume or no-op on the `people`, `api_keys` or `agents` door |
| `binding` | Workflow credential / beneficiary binding events |
| `migration` | `@convex-dev/migrations` backfill rows |
| `security` | Capability URL admission and refusal (`workflow.ingress.accepted`, `workflow.ingress.rejected`) |
| `file_access` | Allowed reads of a stored file (`file_read`), one row per read, written before the file is served |

The two highlighted categories (`governance`, `safety_gate`) carry Trust Fabric decisions and remain fiduciary records — these are the rows compliance and post-incident review will ask for first.

***

## Traceability records

For every governed dispatch, the Trust Fabric also produces a traceability record in the `trustFabricEvents` table — separately from `auditEvents`. The traceability record is structured for compliance forensics and ClickHouse export; the audit row is structured for the operator timeline. Both reference the same dispatch. Like `auditEvents`, this table is **component-only**; it is not in the root Convex schema.

STD-03.3 describes the traceability contract; what is *materialized today* is the column set below. Query against these names — several plausible-sounding packet names (`decisionRecord`, `executionTrace`, `explanationPacket`, `auditRecord`) are **not** columns on this table, and there is no content-hash / environment-ID tamper-evidence column at all.

| Field | What it captures |
| - | - |
| `traceId` | Format `{runId}:{stepId}` — two segments, no timestamp. Deliberately derivable, so post-execution enrichment can re-compute the key and find the row via `by_trace`. |
| `agentId` | The dispatching agent |
| `action` | The dispatch's `stepId` |
| `timestamp` | Epoch milliseconds |
| `disposition` | The governance outcome for the dispatch |
| `gateResults` | Per-gate `{ gate, passed, errorCode? }` — which gates ran and which passed |
| `governancePacket` | Optional, free-form. Written with agent identity, NHI credential ID, owning team, risk tier, fiduciary flag. |
| `costAttribution` | Optional, free-form — cost and token attribution |
| `toolCallCount` | Optional — number of tool calls in the dispatch |
| `toolCallLog` | Optional, per-call detail: `toolName`, `argsHash`, `resultSummary`, `latencyMs`, `costCents`, `timestamp` |
| `lifecyclePhase` | Optional — the agent's lifecycle phase at dispatch |
| `fiduciaryFlag` | Optional boolean — whether the dispatching agent is fiduciary-flagged |

Indexes: `by_trace`, `by_agent`, `by_disposition`, and `by_timestamp`.

Today only workflow dispatch produces these records — chat, factory, and copilot dispatch don't yet. As governance coverage extends to those paths, traceability records will follow.

***

## Authorization denials — where the row survives

A denial is only useful in the audit trail if the row is still there afterwards. A write is one transaction, so a denial row written *inside* a write that is then refused is rolled back with the refusal — the evidence disappears exactly when it matters. Forge therefore never records a denial from inside a read or a write. The refused call fails with a typed error (`data.code === "FORBIDDEN"`, carrying the missing `permissionKey`) and records nothing.

Durable denial rows come from contexts that are not part of a caller's transaction:

| Source | `dispatchSurface` | `reportedBy` |
| - | - | - |
| An HTTP API route refusal — the route runs outside the caller's transaction, so the row is recorded before the 403 is returned | `api` | `server` |
| A console denial, reported back by the operator console's error boundary | `console` | `client` |

Those two are the whole list today; they are the only callers of the denial recorder. Both land in the same `governanceAuditLog` decision record — there is no separate denial table — with `disposition: "block"`, `stepId: "authz"`, and a single `permission` gate result naming the missing key. Filter on *those* fields rather than on a surface name.

A blocked governance gate is a different row, not a missing one. It is also written durably from an action context, but it carries the gate sequence it actually ran and the dispatch's own `stepId`, and its `dispatchSurface` is the dispatch type (`workflow_node`, `agent_tool`, `tool`, `procedure`, `step`, `chat`, and so on) rather than an authorization surface.

**Client-reported rows are not enforcement evidence.** The console is the only observer of a denial raised inside a query or mutation, so it reports what it saw. That report is authenticated, validated against the closed permission catalog, and capped per user per hour. Because the reporter is the client, those rows are excluded by default from:

* the governance overview counts (`blockCount`, `blockRate`) an operator reads as enforcement metrics,
* the compliance export — both halves of it, `GET /api/v3/compliance-export-governance` (the records) and `GET /api/v3/compliance-export-summary` (the counts) — unless you ask for them with `includeClientReported=true`, which both routes accept and interpret identically, and
* the Logs viewer's governance feed. That one is not a metric, but it maps `disposition: "block"` to log level **error** and its return shape cannot carry the `reportedBy` label — so an unverified self-report would render there as an ERROR-level governance block, indistinguishable from enforcement. It also reads the newest rows per disposition off the index, where a denial is the newest `block` row by construction.

Rows written before the `reportedBy` label existed carry no value and are treated as server-side, so the label never shortens a historical export. The exclusion is applied inside the index range rather than to the fetched page, so an excluded row never displaces a real decision out of a capped window.

**A denial row is not a latency sample, a gate result, or a dispatch — whoever reported it.** Every denial carries `stepId: "authz"`, no `durationMs`, and one synthetic always-failing `permission` gate. Three surfaces therefore exclude the whole authz step rather than a reporter: the governance p99 in the weekly performance report, the per-gate pass/block tallies on the Gates dashboard, and the "recent blocked dispatches" card. That exclusion is by `stepId`, not by `reportedBy`, because a server-observed denial *is* real enforcement evidence — it stays in the compliance export, the overview counts and the decision aggregates. It just cannot express latency, it is not an engine gate outcome, and it is not a dispatch.

`permission` *is* a real member of the governance gate sequence, which is precisely why the exclusion is by `stepId` and not by gate name. A denial row's `permission` result is an authorization refusal wearing a gate-shaped field — always failing, never marked skipped, and never produced by the engine evaluating that gate. Counting it would conflate the authz seam with the real gate, so the gate's genuine pass rate would read as polluted by every 403 the platform served.

The displacement risk is what makes this load-bearing rather than cosmetic. `by_disposition` is keyed `[disposition, timestamp]`, so on the `block` leg a denial is among the *newest* rows by construction — any reader that takes the newest N blocks would otherwise show denials and crowd genuine decisions out of a capped window entirely.

A client-reported row is also deliberately unattached: its `runId` is the constant `authz:console`, never a workflow run, so a report cannot appear on a run's audit packet as if a gate had blocked that run. The route the person was on is recorded in the row's `explanation`. Read a client-reported row for what it is: a person hit a wall on a specific page, which is worth knowing when you are calibrating entitlements — and is not a claim that a gate held.

Where you can read them is the decision explorer on Trust Fabric → Decisions, which returns whole rows and keeps the `reportedBy` field. **The console does not render that field yet**, so on that page a self-report currently looks like any other `block`. Until it does, tell the two apart by the fields the row does show: a denial has `stepId: "authz"`, a single `permission` gate, and a `runId` of `authz:console` (client) or a route path (server) rather than a workflow run id. The compliance export carries `reportedBy` verbatim, so a scripted read can filter on it today.

***

## The `permission` gate — what a decision row says about authority

The `permission` gate answers a different question from the authorization denials above: not "may
this person call this function" but "may this dispatch's *principal* take this action". It is a real
member of the governance gate sequence, evaluated in the engine's early phase right after the
identity check, and it runs on three surfaces:

| Surface | Where it runs | `dispatchSurface` on the row |
| - | - | - |
| Agent dispatch | The governance engine's early phase | `step`, `delegated_run`, `chat`, `factory_dispatch`, … |
| Tool call | The one tool seam, before the tool body | `tool` |
| Procedure invocation | The procedure gate pipeline, after identity | `procedure` |

A procedure invocation is the newest of the three. It previously produced only a
`procedureInvocationAudits` row, so the decision record — and every metric built on it — was silent
about that surface. It now writes a `governanceAuditLog` row like any other dispatch.

**What the row records is the shortfall, not the authority.** The gate computes
`effective = principal ∩ role ∩ tier`; a required key absent from that intersection lands on the row
as `missingPermissionKeys`. The keys the principal *holds* are never persisted — that snapshot is
resolved once per dispatch and is an input to the decision, not part of it. So a decision row can
tell you what an action needed and did not have; it cannot be mined for who can do what. Read
entitlements from the entitlement surfaces instead.

**The gate has two evaluation arms, and they mean different things.** (A third code,
`required_keys_undeclared`, comes from the tool seam rather than from the gate's own evaluation —
see *An undeclared tool is not an unrestricted one* below.)

* `permission_denied` — the principal resolved, and a required key was missing.
  `missingPermissionKeys` names exactly which.
* `principal_unresolved` — the dispatch could not be attributed to anyone. This is a refusal, not a
  pass: an action nobody is accountable for is the case the gate exists to stop.

**Enforced decisions.** The permission gate refuses a missing key or an unresolved principal.
`missingPermissionKeys` records the required keys that were absent; `blockedByGate` identifies
the control that refused the action. Agent and tool decisions also retain the gate result's
`errorCode`, including `permission_denied`, `principal_unresolved`, and
`required_keys_undeclared`. The retired shadow flag is absent from decision storage and exports.

Passed gate results may still carry advisory causes such as `nhi_not_configured`,
`si02_no_hash`, `si02_version_resolution_error`, or
`policy_advisory_require_approval_not_held`. A passed result is advisory evidence; stopping-check
readers and gate statistics select `passed: false`. Publish-judge `warn` remains a separate advisory
mode and records its audit event.

**An undeclared tool is not an unrestricted one.** The keys an action requires come from its own
definition. A tool or procedure that declares `requiredPermissionKeys: []` requires no *key*, so it
has no key to be missing. One that declares *nothing at all* falls to a stricter default: an
`internal` tool is evaluated against `tools:read`, and an `external` tool is refused outright with
`required_keys_undeclared`, because defaulting an outbound call to a read-shaped key would authorize
egress on the weakest key in the catalog.

An empty required set is not a bypass of the gate. `principal_unresolved` is decided before the
required keys are consulted at all, so a dispatch nobody could be attributed to is still refused
even when the action it was calling required nothing. Declaring `[]` waives the key check, never the accountability check.

## Protected data classification

STD-06 defines six duty-of-care classes for data flowing through agent interactions. Read this section as the **standard's taxonomy, not a shipped audit feature** — see the warning below it before you plan a compliance workflow around it.

| Class | Color | Duty of care |
| - | - | - |
| pastoral\_counseling | Red — confessional-grade | Spiritual direction, pastoral conversations |
| mental\_health\_indicator | Red — clinical sensitivity | Psychological distress signals, behavioral health |
| crisis\_state\_communication | Red — immediate welfare | Active crisis disclosures, safety concerns |
| donor\_vulnerability | Orange — financial privacy | Giving capacity signals, vulnerability indicators |
| financial\_transaction | Orange — transactional integrity | Payment data, transaction records |
| none | Green — baseline | Standard operational data |

Not yet on the audit row

**No audit row carries a fiduciary class today, and no audit view can be filtered by one.** The six-class enum (`FIDUCIARY_DATA_CLASSES`) exists in the `forge-governance` component but has no consumers: nothing writes a class onto `auditEvents`, `governanceAuditLog`, or `trustFabricEvents`, and no query or console filter accepts one. Do not plan a compliance workflow around a class filter, and do not read the classes above as a guarantee about the historical record.

What the durable record *does* carry per dispatch is `fiduciaryFlag` — a boolean on `trustFabricEvents`, taken from the dispatching agent's own `fiduciaryFlag` and mirrored inside `governancePacket`. It tells you the agent was fiduciary-flagged at dispatch; it does not tell you which class of data it touched, and it is not indexed, so it is not a filter dimension either.

The filter dimensions that do exist on audit rows are `category`, `resourceType` / `resourceId`, `actorType`, `runId`, and a full-text search over `event`. In the console's audit view they surface as time range, category, and search.

***

## Evidence explorer and reports

The Console [Decisions](https://docs.gloo.com/forge/console/trust-fabric/decisions.md) page reads organization-scoped decision evidence with fixed-window, filter-bound cursor pagination. Exact recorded person, run, step, agent, tool, policy, gate, and dispatch-surface fields are shown when present; absent historical values remain `Unknown`. Client-reported evidence is excluded by default and visibly labeled when included.

The Reports tab on [Decisions](https://docs.gloo.com/forge/console/trust-fabric/decisions.md) provides bounded reports with explicit scanned, eligible, unknown, sampled, and coverage metadata. Its on-behalf-of access report shows current-grant-only context for a validated published run's version. It no longer correlates approvals, because approvals stopped recording grant descriptors. Current grants are never used to reconstruct historical authority.

JSON, Markdown, and RFC 4180 CSV exports describe their authorized organization scope, fixed filters/window, loaded population, and coverage. A capped scan, sampled aggregate, unavailable source, or loaded-row cap remains labeled as such in the export.

### Compliance exports over the Platform API

Three reads cover a window of at most 90 days: `GET /api/v3/compliance-export-audit` pages the audit events, `GET /api/v3/compliance-export-governance` pages the governance decision records, and `GET /api/v3/compliance-export-summary` counts the decisions. `startTime` and `endTime` are epoch milliseconds; make several requests for a longer period.

```bash theme={null}
END=$(( $(date +%s) * 1000 ))
START=$(( END - 7 * 24 * 60 * 60 * 1000 ))
curl -sS "$FORGE_BASE/api/v3/compliance-export-audit?startTime=$START&endTime=$END&limit=500" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data | {pageCount, cursor, first: .records[0]}'
```

Each page is newest first, up to 1,000 records (`limit`). Pass the page's `data.cursor` back as `cursor` until it is `null`; add `category` to export one audit category. Over MCP, `forge_call_read_operation` runs the same export:

```json theme={null}
{ "operationId": "exportAuditEvents", "input": { "startTime": 1762128000000, "endTime": 1762732800000, "limit": 500 } }
```

The quickstart's `ACCESS_TOKEN` does not carry `audit:read`: mint a token with `scope=audit:read`, or send a Personal key whose scopes include it. Compliance exports cover the whole deployment, so they require `audit:read` granted at the deployment root; a credential granted only below it receives 403. A key or app holding `audit:read` at a tenant org unit, or at a partner organization's own root, gets `403 forbidden` with `requiredPermission: "audit:read"`, and the refusal is recorded as an authorization denial. Platform-scope grants and every migrated key's root compatibility grant keep the exports.

Records keep their stored shape, including `principal`, because the reader is a deployment-root auditor. The governance export pages to the end of any window; a page that had to skip records sharing one millisecond says `partial: true` with `saturatedAt`. See [Compliance](https://docs.gloo.com/forge/reference/http-api/compliance).

***

## Retention

A daily retention sweep deletes audit events older than 365 days. It caps each run at 2,000 deletes or 20 seconds of elapsed time to stay within mutation limits, and resumes simply by scanning oldest-first: the rows it removes *are* the progress, so the next run necessarily starts after the last one. There is no stored cursor to get stuck. Retention is currently a flat 365 days across all categories — there is no category-level override today.

Related signals have their own sweeps: token events and execution events run on independent retention periods.

If your compliance regime requires longer than 365-day retention (some financial / health / pastoral contexts do), configure an external archive: page the [compliance exports](#compliance-exports-over-the-platform-api) into S3 or a data warehouse on a schedule, and treat Forge's retention as the working window, not the system of record.

***

## Operator runbook

When you operate the audit surface day-to-day:

1. **Build saved filters for your common questions.** "All governance decisions for the Customer Success team this week" or "every approval rejected in the last 30 days." Operators who type the filter every time eventually stop looking.
2. **Pull run audit packets early.** The moment a run looks suspicious, export its packet. It is much faster to look at the export than to re-navigate the live UI when the question turns into a multi-stakeholder review.
3. **Review an export by hand before sharing.** The audit row carries no data classification, so nothing marks a sensitive row for you. Read the `detail` payloads in a packet you are about to hand to a stakeholder — the export carries whatever the emitter put there, and the recipient may not have access to the underlying data.
4. **Archive before the window closes.** Retention deletes audit events after 365 days. If you need them longer, export each window well before its oldest events reach that age.

***

## Related

* [Trust Fabric in production](https://docs.gloo.com/forge/run/trust-fabric.md)
* [Observability](https://docs.gloo.com/forge/run/observability.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.