Skip to main content
GET
List recorded Trust Fabric decisions
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Pages the Trust Fabric decisions recorded for your credential’s acting organization in a time window, newest first. Each item is recorded evidence only. Forge doesn’t re-run policy or preview what would happen today.

Who can read the list

Your credential sets the actor and the organization: a platform or MCP key, or an External App token, acting within its organization. You can’t choose another organization, audience, view, actor or person. A request that includes orgUnitId, view, audience, actor, personId or any other unlisted parameter returns 400. A credential with no acting organization receives 403. Your actor must still hold grants:read, policies:read and audit:read at that organization. Forge checks those grants again on every page, including continuations. A decision appears only when it was recorded or reconciled for exactly your acting organization and has no private fence. Personal, platform-wide, private-chat, legacy and unresolved decisions never appear, and neither does another organization’s decision. That holds for a Platform admin’s key and for an app owner too.

Parameters

Each parameter may appear once. Filters apply after Forge decides you may see a row, so a filter can’t reveal a decision you couldn’t otherwise read.

Coverage

A page returns items, continueCursor, isDone, coverage, resolutionRevision and coverageBlocker. One request scans at most 2,000 recorded rows.
  • coverage.examined counts the rows you may see that the scan reached, and coverage.eligible counts those that also matched your filters. Hidden rows are never counted.
  • coverage.status is complete only when the scan read the window to the end.
  • partial means the scan cap, the evidence read budget or remaining pages stopped it. Continue with continueCursor.
  • unavailable means the source failed, too many decisions share one timestamp, or (reason unresolved_attribution) the scan met a decision whose organization was never resolved, such as a legacy record. That decision might belong to your organization and no machine reader is shown it, so Forge can’t claim the page is complete, even when examined equals eligible. Those decisions come from writers that recorded no organization, not from your query, so narrowing the window or filters won’t change that reason.
  • coverageBlocker repeats the result as none, partial or unavailable.
An empty or short page is proof of nothing unless coverage.status is complete.

Continuing a list

Pass continueCursor back as cursor with every other parameter unchanged. The cursor is an opaque, sealed token. Treat it as a string and don’t parse it or build one. It is bound to your credential, its acting organization, resolutionRevision, the window, limit and every filter. If any of them changes, or the recorded evidence was reconciled since the first page, the request returns 400. Start the list again without a cursor. An altered cursor, or one issued before Forge rotated its signing keys, also returns 400. A cursor isn’t an authorization. Losing a grant between pages returns 403. isDone is true exactly when continueCursor is null. A scan that can’t move on (a source outage, or a position the source can’t page past) ends as done, and coverage says why; an unavailable page is never proof that nothing more exists.

What each item contains

Each item has the same decision, causes and remediation as Explain a recorded decision. It never contains the principal, role, policy, gate messages or the free-text explanation. Each item also carries correlation: the recorded runId, stepId and dispatchId of the dispatch the decision was made for. The correlation identifies that dispatch. It doesn’t grant access to the run or step, and a later run read checks its own authorization. With includeDecisionFields=true, each item also carries the recorded fields that name no person: policyId, dispatchSurface, missingPermissionKeys, blockedByGate (a legacy column, usually null), heldBy (the holding policy’s name), retryable, and evidence.sourceKind (what the evidence was about; for workflow_launch, correlation.runId is a launch label, not a run id).

Example

Over MCP, forge_call_operation with operationId listGovernanceEvidence returns the same data and meta as its body. See MCP server.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

startAt
integer
required

Window start, epoch milliseconds (inclusive). Must be before endAt.

Required range: x >= 0
endAt
integer
required

Window end, epoch milliseconds (inclusive).

Required range: x >= 0
limit
integer
required

Maximum items on this page, 1 to 100.

Required range: 1 <= x <= 100
cursor
string

The previous page's continueCursor, with every other parameter unchanged.

Minimum string length: 1
disposition
enum<string>

Only decisions with this disposition.

Available options:
pass,
block,
hold
runId
string

Only decisions whose correlation.runId is this run.

Minimum string length: 1
agentId
string

Only decisions recorded for this agent.

Minimum string length: 1
gate
string

Only decisions with a recorded result for this gate.

Minimum string length: 1
gateOutcome
enum<string>

With gate: only decisions where that gate ran and failed. Without gate it is 400.

Available options:
failed
dispatchSurface
string

Only decisions recorded on this dispatch surface.

Minimum string length: 1
policyId
string

Only decisions recorded against this policy.

Minimum string length: 1
includeClientReported
enum<string>
default:false

Include client-reported decisions. Defaults to false (server-recorded only).

Available options:
true,
false
includeDecisionFields
enum<string>
default:false

With true, each item adds the recorded non-person decision fields: policyId, dispatchSurface, missingPermissionKeys, blockedByGate, heldBy, retryable and evidence.sourceKind. It filters nothing and is not bound to the cursor.

Available options:
true,
false

Response

A page of recorded decisions with its coverage

data
object
required
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.