Evidence Graph

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

The evidence graph is the governance audit trail for a single execution. Starting from an execution ID, it traces backward through every decision that shaped the run: which release was active, which workload it belongs to, which asset versions were bound, what the policy decided, which obligations were emitted, what was retrieved from knowledge bases, what evidence artifacts were produced, and who approved the release.

Use the evidence graph to investigate a bad execution, respond to a compliance audit, or verify that obligations were fulfilled.

Node and edge model

The graph is made up of typed nodes connected by labeled edges.

Node types

Node type	Represents
`execution`	The individual flow run
`release`	The release that was active when the execution ran
`workload`	The workload owning the release
`binding`	An asset version bound to the release (prompt, model, guardrail, policy bundle, etc.)
`policy_decision`	The outcome produced by the policy engine for this execution
`retrieval_event`	A knowledge-base retrieval that occurred during the execution
`evidence_artifact`	An artifact captured as compliance evidence (logs, traces, snapshots)
`approval`	A release approval record

Edge relationships

Relationship	Source	Target
`executed_under`	`execution`	`release`
`belongs_to`	`release`	`workload`
`binds`	`release`	`asset`
`governed_by`	`execution`	`policy_decision`
`requires`	`policy_decision`	`obligation`
`retrieved`	`execution`	`retrieval_event`
`produced`	`execution`	`evidence_artifact`
`approved_by`	`release`	`approval`

Endpoint


GET /v1/executions/{id}/evidence-graph?format=flat|graph

The format query parameter controls the response shape. It defaults to flat.

Flat format

The flat format returns a pre-joined document with all governance data in a single response. No client-side graph traversal is required.


GET /v1/executions/{id}/evidence-graph?format=flat

Response shape:


{
  "format": "flat",
  "execution": {
    "execution_id": "ex1a2b3c-0000-0000-0000-000000000001",
    "workload_id": "w1a2b3c4-0000-0000-0000-000000000001",
    "release_id": "r1a2b3c4-0000-0000-0000-000000000010",
    "started_at": "2026-04-11T09:45:00Z",
    "finished_at": "2026-04-11T09:45:03Z",
    "status": "completed"
  },
  "release": {
    "release_id": "r1a2b3c4-0000-0000-0000-000000000010",
    "environment": "production",
    "lifecycle_state": "active"
  },
  "workload": {
    "workload_id": "w1a2b3c4-0000-0000-0000-000000000001",
    "slug": "customer-support-bot",
    "owner_ref": "team:cx-platform"
  },
  "bindings": [
    {
      "role": "prompt_template",
      "asset_version_id": "av-prompt-v2",
      "asset_slug": "support-prompt"
    },
    {
      "role": "policy_bundle",
      "asset_version_id": "av-policy-v3",
      "asset_slug": "content-safety-policy"
    },
    { "role": "guardrail", "asset_version_id": "av-guard-v1", "asset_slug": "pii-guardrail" }
  ],
  "policy_decision": {
    "outcome": "allow_with_obligations",
    "reason_code": "MEDICAL_CONTENT",
    "evaluated_at": "2026-04-11T09:45:00Z"
  },
  "obligations": [
    { "obligation_name": "capture_evidence", "fulfilled_at": "2026-04-11T09:45:03Z" },
    { "obligation_name": "require_human_review", "fulfilled_at": "2026-04-11T09:45:04Z" }
  ],
  "retrieval_events": [
    {
      "retrieval_event_id": "re1a2b3c-0000-0000-0000-000000000001",
      "knowledge_base_asset_id": "kb-prod-docs",
      "query_text": "refund policy for international orders",
      "retrieved_chunk_count": 4,
      "retrieved_at": "2026-04-11T09:45:01Z"
    }
  ],
  "evidence_artifacts": [
    {
      "artifact_id": "ea1a2b3c-0000-0000-0000-000000000001",
      "artifact_kind": "full_request_log",
      "storage_ref": "evidence/ex1a2b3c/full_request.json.gz",
      "created_at": "2026-04-11T09:45:03Z"
    }
  ],
  "approvals": [
    {
      "approval_id": "ap1a2b3c-0000-0000-0000-000000000001",
      "approved_by": "user:compliance-officer",
      "approved_at": "2026-04-10T14:00:00Z",
      "note": "Approved after security review"
    }
  ]
}

Graph format

The graph format returns the same data as a nodes-and-edges structure, suited for visualization or graph-processing libraries.


GET /v1/executions/{id}/evidence-graph?format=graph

Response shape:


{
  "format": "graph",
  "nodes": [
    {
      "id": "ex1a2b3c-0000-0000-0000-000000000001",
      "type": "execution",
      "data": {
        /* ... */
      }
    },
    {
      "id": "r1a2b3c4-0000-0000-0000-000000000010",
      "type": "release",
      "data": {
        /* ... */
      }
    },
    {
      "id": "w1a2b3c4-0000-0000-0000-000000000001",
      "type": "workload",
      "data": {
        /* ... */
      }
    },
    {
      "id": "av-policy-v3",
      "type": "asset",
      "data": {
        /* ... */
      }
    },
    {
      "id": "pd1a2b3c-0000-0000-0000-000000000001",
      "type": "policy_decision",
      "data": {
        /* ... */
      }
    },
    {
      "id": "ob-log-full-request",
      "type": "obligation",
      "data": {
        /* ... */
      }
    },
    {
      "id": "re1a2b3c-0000-0000-0000-000000000001",
      "type": "retrieval_event",
      "data": {
        /* ... */
      }
    },
    {
      "id": "ea1a2b3c-0000-0000-0000-000000000001",
      "type": "evidence_artifact",
      "data": {
        /* ... */
      }
    },
    {
      "id": "ap1a2b3c-0000-0000-0000-000000000001",
      "type": "approval",
      "data": {
        /* ... */
      }
    }
  ],
  "edges": [
    {
      "source": "ex1a2b3c-0000-0000-0000-000000000001",
      "target": "r1a2b3c4-0000-0000-0000-000000000010",
      "relationship": "executed_under"
    },
    {
      "source": "r1a2b3c4-0000-0000-0000-000000000010",
      "target": "w1a2b3c4-0000-0000-0000-000000000001",
      "relationship": "belongs_to"
    },
    {
      "source": "r1a2b3c4-0000-0000-0000-000000000010",
      "target": "av-policy-v3",
      "relationship": "binds"
    },
    {
      "source": "ex1a2b3c-0000-0000-0000-000000000001",
      "target": "pd1a2b3c-0000-0000-0000-000000000001",
      "relationship": "governed_by"
    },
    {
      "source": "pd1a2b3c-0000-0000-0000-000000000001",
      "target": "ob-log-full-request",
      "relationship": "requires"
    },
    {
      "source": "ex1a2b3c-0000-0000-0000-000000000001",
      "target": "re1a2b3c-0000-0000-0000-000000000001",
      "relationship": "retrieved"
    },
    {
      "source": "ex1a2b3c-0000-0000-0000-000000000001",
      "target": "ea1a2b3c-0000-0000-0000-000000000001",
      "relationship": "produced"
    },
    {
      "source": "r1a2b3c4-0000-0000-0000-000000000010",
      "target": "ap1a2b3c-0000-0000-0000-000000000001",
      "relationship": "approved_by"
    }
  ]
}

Each data object contains the same fields shown in the flat format for that node type.

Portal: Evidence tab on execution detail

The Evidence tab on the execution detail view provides two sub-views:

Flat view — collapsible sections for each governance layer: Release, Workload, Bindings, Policy Decision, Obligations, Retrieval Events, Evidence Artifacts, and Approvals. Each section renders the relevant fields with links to related portal pages.
Graph view — a visual canvas (ReactFlow) where each node type has a distinct shape and color. Edges are labeled with relationship names. Clicking any node opens a side panel with its full data. The graph is read-only; it reflects the state at execution time.

The flat view is the default because it renders faster and is easier to export. The graph view is useful for understanding the governance chain visually during an incident.

SDK


from orqestra_sdk import OrqestraClient
 
async with OrqestraClient() as client:
    # Flat format (default) — pre-joined document
    evidence = await client.executions.evidence_graph(
        "ex1a2b3c-0000-0000-0000-000000000001",
        format="flat",
    )
 
    # evidence is a plain dict matching the flat response schema above
    print(evidence["policy_decision"]["outcome"])
    print(evidence["policy_decision"]["reason_code"])
 
    for binding in evidence["bindings"]:
        print(binding["role"], binding["asset_slug"])
 
    for artifact in evidence["evidence_artifacts"]:
        print(artifact["artifact_kind"], artifact["storage_ref"])
 
    # Graph format — nodes and edges
    graph = await client.executions.evidence_graph(
        "ex1a2b3c-0000-0000-0000-000000000001",
        format="graph",
    )
 
    for node in graph["nodes"]:
        print(node["type"], node["id"])
 
    for edge in graph["edges"]:
        print(edge["source"], "->", edge["relationship"], "->", edge["target"])

CLI

Retrieve the evidence graph


orqestractl execution evidence-graph <execution-id>

Default output is the flat format rendered as collapsible text sections:


EXECUTION   ex1a2b3c   completed   2026-04-11T09:45:00Z
RELEASE     r1a2b3c4   production  active
WORKLOAD    customer-support-bot   team:cx-platform

BINDINGS
  prompt_template   support-prompt       av-prompt-v2
  policy_bundle     content-safety-policy  av-policy-v3
  guardrail         pii-guardrail        av-guard-v1

POLICY DECISION
  outcome:     allow_with_obligations
  reason_code: MEDICAL_CONTENT

OBLIGATIONS
  capture_evidence        fulfilled 2026-04-11T09:45:03Z
  require_human_review    fulfilled 2026-04-11T09:45:04Z

RETRIEVAL EVENTS
  kb-prod-docs   "refund policy for international orders"   4 chunks

EVIDENCE ARTIFACTS
  full_request_log   evidence/ex1a2b3c/full_request.json.gz

APPROVALS
  user:compliance-officer   2026-04-10T14:00:00Z

Graph format output


orqestractl execution evidence-graph <execution-id> --format graph

Returns the nodes-and-edges JSON structure. Pipe to jq or forward to a visualization tool.

JSON output

Add --json to either invocation for machine-readable output:


orqestractl execution evidence-graph <execution-id> --json
orqestractl execution evidence-graph <execution-id> --format graph --json

Context-lineage evidence read

To inspect context-lineage and high-consequence-action evidence recorded for one execution, use the authenticated API relative to your deployment’s control-plane address:


GET /v1/executions/{execution_id}/context-lineage?workspace_id={workspace_id}&limit=50&offset=0

The route requires execution.view and applies execution/workspace scope. It accepts optional origin, influence_role, and action_class filters. limit is bounded to 1–200; the response contains the total, offset, limit, and items. Continue paging when needed.

Read-grade actors receive bounded summary fields. Additional operator disclosure requires execution.kill on that execution’s workspace and can include bounded action-posture, untrusted-reason, and decision-evidence references. Missing, redacted, unavailable, or archived payload details must not be interpreted as proof that context was absent. This evidence read is separate from the assistant’s visible Sources and Recalled context sections; the current assistant does not mount a Context provenance panel.