Get the shadow disagreement report

GET

/v1/insights/shadow

const url = 'http://127.0.0.1:8080/v1/insights/shadow?shadow_version=pv_01m42va0ryp515cvtem633vqng';
const options = {
  method: 'GET',
  headers: {'Deedglass-Version': '2026-10-01', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://127.0.0.1:8080/v1/insights/shadow?shadow_version=pv_01m42va0ryp515cvtem633vqng' \
  --header 'Authorization: Bearer <token>' \
  --header 'Deedglass-Version: 2026-10-01'

Where the shadow policy and the enforced one disagreed on live traffic (S27): the actions the shadow version evaluated, how many it agreed on (agreement = agree / evaluated, 4 decimals), and every disagreement as a transition from the enforced decision to the shadow one, by rule (the shadow’s deciding rule), tool and agent, with the first 20 action ids and, for actions the enforced policy sent to approval, what people did with them. enforce lists the enforced versions that decided those actions. sentence is the one line the Console and deedglass insights shadow print. Rows are chosen by the shadow version recorded on each action, never by activation time. shadow_version (a pv_ id) reads a past shadow version; the default is the live one, and with none live the answer is 404 not_found. from and to (RFC 3339, each optional) narrow the window; from not before to is 400 replay_window_invalid. A Console session (viewer and up) or an org admin key (admin scope); agent keys get 403 insufficient_scope.

Authorizations

bearerAuth
sessionCookie

Parameters

Header Parameters

Deedglass-Version

string

/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/

The API version (YYYY-MM-DD). Leave it out to use your org’s pinned version (public routes use the latest). An unknown version is 400 api_version_invalid.

Query Parameters

shadow_version

string

A shadow version (pv_…). Default the live one.

Example

pv_01m42va0ryp515cvtem633vqng

from

string format: date-time

Actions decided at or after this time (RFC 3339).

string format: date-time

Actions decided before this time (RFC 3339).

Responses

200

The report.

application/json

object

object

required

string

Allowed value: shadow_report

shadow

required

object

policy

required

The policy id (pol_…).

string

name

required

string

version

required

integer

>= 1

version_id

required

The version id (pv_…).

string

live

required

It is the active shadow version now.

boolean

since

When it became the shadow version.

string format: date-time

enforce

required

The enforced versions that decided the report’s actions.

Array<object>

object

name

required

string

version

required

integer

version_id

required

string

actions

required

integer

window

required

object

from

required

string | null format: date-time

required

string | null format: date-time

summary

required

object

evaluated

required

integer

agree

required

integer

disagree

required

integer

agreement

required

Agree / evaluated

number

transitions

required

Array<object>

Every action the shadow version would have decided differently. The full ShadowTransition schema is in openapi.yaml.

object

sentence

required

The one line the Console and the CLI print.

string

Examples

live

acme-sim v2 in shadow next to v1 (three samples shown per transition)

{
  "object": "shadow_report",
  "shadow": {
    "policy": "pol_01m42v9q4bjwfqmk8bd58vzkdh",
    "name": "acme-sim",
    "version": 2,
    "version_id": "pv_01m42va0ryp515cvtem633vqng",
    "live": true,
    "since": "2026-10-04T06:58:31.330501Z"
  },
  "enforce": [
    {
      "name": "acme-sim",
      "version": 1,
      "version_id": "pv_01m42v9q4bjwfqmk8bd58vzkdj",
      "actions": 4179
    }
  ],
  "window": {
    "from": null,
    "to": null
  },
  "summary": {
    "evaluated": 4179,
    "agree": 4004,
    "disagree": 175,
    "agreement": 0.9581
  },
  "transitions": [
    {
      "enforce": "allow",
      "shadow": "require_approval",
      "count": 158,
      "by_rule": [
        {
          "rule_id": "refund-approval-over-30",
          "count": 158
        }
      ],
      "by_tool": [
        {
          "tool": "stripe.create_refund",
          "count": 158
        }
      ],
      "by_agent": [
        {
          "agent": "agt_01m42v9q3v1av7wvzjr1kq3mx1",
          "name": "support-bot",
          "count": 158
        }
      ],
      "samples": [
        "act_01m42va0xa6fjkr9xbwsst1fzw",
        "act_01m42va1567ecpzdb2g1td5n56",
        "act_01m42va1bf0w9q777sp2eqh2mq"
      ]
    },
    {
      "enforce": "allow",
      "shadow": "deny",
      "count": 17,
      "by_rule": [
        {
          "rule_id": "slack-allowlist",
          "count": 17
        }
      ],
      "by_tool": [
        {
          "tool": "slack.post_message",
          "count": 17
        }
      ],
      "by_agent": [
        {
          "agent": "agt_01m42v9q4500m4rfchvb8j53da",
          "name": "growth-agent",
          "count": 17
        }
      ],
      "samples": [
        "act_01m42va25mvsydk6j93ee0wc9p",
        "act_01m42va2ered5fbrvrzkqzbqpq",
        "act_01m42va3gdnqdf3acgkxan6ebb"
      ]
    }
  ],
  "sentence": "Shadow acme-sim v2 would have sent 158 actions to approval and denied 17 that v1 allowed (refund-approval-over-30: 158, slack-allowlist: 17)."
}

Headers

Deedglass-Request-Id

string

/^req_[0-7][0-9a-hjkmnp-tv-z]{25}$/

This request’s id. Quote it to support; it matches error.request_id.

Deedglass-Version

string

The API version this response follows.

404

No shadow policy is active (or no such version).

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error policy_error rate_limit_error api_error

code

required

string

Allowed values: invalid_api_key api_key_revoked api_key_expired agent_suspended agent_stopped org_stopped insufficient_scope policy_denied approval_required approval_expired budget_exceeded intent_required intent_invalid intent_replay tool_unknown connector_unavailable upstream_error timeout rate_limited idempotency_conflict validation_failed not_found conflict internal_error authentication_required method_not_allowed request_too_large unsupported_media_type invalid_json api_version_invalid idempotency_key_invalid idempotency_key_in_use service_unavailable session_expired csrf_failed insufficient_role login_link_invalid login_code_invalid last_owner policy_unavailable policy_invalid credentials_missing destination_blocked vault_unavailable upstream_auth_failed upstream_not_found upstream_rate_limited response_too_large statement_refused row_limit_exceeded database_role_unsafe database_not_ready witness_not_configured approval_decided already_countersigned approver_not_eligible self_approval approval_needs_person context_changed approval_unsatisfiable approval_link_invalid approval_link_review_only approver_unmapped stripe_live_key_refused stripe_livemode_detected upstream_approval_pending schedule_needs_approval action_executing from_denied undo_unavailable undo_plan_stale already_undone undo_conflict replay_too_large replay_window_invalid suggestion_stale shadow_slot_taken suggestion_decided observe_not_enabled pro_required

message

required

One or more calm sentences with the next step.

string

param

required

The request field, query parameter or header the error is about.

string | null

request_id

required

string

/^req_[0-7][0-9a-hjkmnp-tv-z]{25}$/

doc_url

required

string format: uri

diagnostics

On policy_invalid only. Each problem with its line, code and hint.

Array<object>

One finding about a policy file, with its position and the next step. Codes are stable and listed in docs/POLICY_ERRORS.md. In the policy_invalid error envelope each diagnostic also carries object: policy_diagnostic. The full PolicyDiagnostic schema is in openapi.yaml.

object

action

One agent action. Its sections mirror the deed’s. status is the one field an agent needs; state is the exact lifecycle state (docs/GATE.md). The Gate’s own responses (POST /v1/actions and its result report) add execution.result and witness.reasons; lists leave both out. The full Action schema is in openapi.yaml.

object

checks

On undo_unavailable only. Every check of the undo, each with its fix. Additive (S23).

Array<object>

One of the twelve safety checks (S23 §3.3). Available means no check failed. The full UndoCheck schema is in openapi.yaml.

object

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "No shadow policy is active in this org. Run one: deedglass policy activate <name> --version <n> --mode shadow --reason \"…\"",
    "param": null,
    "request_id": "req_01m42vmb2c4e6g8j0m2p4r6t8v",
    "doc_url": "https://docs.deedglass.com/errors/not_found"
  }
}

Headers

Deedglass-Request-Id

string

/^req_[0-7][0-9a-hjkmnp-tv-z]{25}$/

This request’s id. Quote it to support; it matches error.request_id.

default

An error. Every error has this envelope; doc_url explains the code.

application/json

object

error

required

object

type

required

string

Allowed values: invalid_request_error authentication_error permission_error policy_error rate_limit_error api_error

code

required

string

message

required

One or more calm sentences with the next step.

string

param

required

The request field, query parameter or header the error is about.

string | null

request_id

required

string

/^req_[0-7][0-9a-hjkmnp-tv-z]{25}$/

doc_url

required

string format: uri

diagnostics

On policy_invalid only. Each problem with its line, code and hint.

Array<object>

object

action

object

checks

On undo_unavailable only. Every check of the undo, each with its fix. Additive (S23).

Array<object>

One of the twelve safety checks (S23 §3.3). Available means no check failed. The full UndoCheck schema is in openapi.yaml.

object

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "There's no endpoint at GET /v1/helth. Did you mean /v1/health?",
    "param": null,
    "request_id": "req_01j9zr3m5k8q2w7x4t6v0b1c9d",
    "doc_url": "https://docs.deedglass.com/errors/not_found"
  }
}

Headers

Deedglass-Request-Id

string

/^req_[0-7][0-9a-hjkmnp-tv-z]{25}$/

This request’s id. Quote it to support; it matches error.request_id.

Deedglass-Version

string

The API version this response follows.