> ## Documentation Index
> Fetch the complete documentation index at: https://agenticadvertisingorg-ohalushchak-exadel-context-match-sell.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# get_plan_audit_logs

> get_plan_audit_logs retrieves governance state, budget tracking, and a complete audit trail for AdCP campaign plans or portfolios.

# get\_plan\_audit\_logs

<Note>
  **Experimental.** Campaign governance (`sync_plans`, `check_governance`, `report_plan_outcome`, `get_plan_audit_logs`) is part of AdCP 3.0 as an experimental surface — it may change between 3.x releases with at least 6 weeks' notice. Sellers implementing it MUST declare `governance.campaign` in `experimental_features`. See [experimental status](/dist/docs/3.1.0-rc.7/reference/experimental-status) for the full contract.
</Note>

Retrieve governance state and audit trail for a plan, multiple plans, or an entire portfolio. Returns budget tracking, validation history, and compliance summary.

## Request

```json theme={null}
{
  "tool": "get_plan_audit_logs",
  "arguments": {
    "plan_ids": ["plan_q1_2026_launch"],
    "include_entries": true
  }
}
```

Results are grouped by `governance_context` within each plan. Each governed action (media buy, rights license, signal activation, creative service) appears under its `governance_context`.

**Multiple plans** -- retrieve specific plans in one call:

```json theme={null}
{
  "tool": "get_plan_audit_logs",
  "arguments": {
    "plan_ids": ["plan_q1_2026_launch", "plan_q1_2026_emea"],
    "include_entries": false
  }
}
```

**Portfolio query** -- retrieve combined audit data for all member plans in one or more portfolios:

```json theme={null}
{
  "tool": "get_plan_audit_logs",
  "arguments": {
    "portfolio_plan_ids": ["portfolio_nova_brands_2026"],
    "include_entries": true
  }
}
```

You can combine `plan_ids` and `portfolio_plan_ids` to query both specific plans and portfolios in a single call.

## Response

```json theme={null}
{
  "plans": [
    {
      "plan_id": "plan_q1_2026_launch",
      "plan_version": 1,
      "status": "active",
      "budget": {
        "authorized": 500000,
        "committed": 425000,
        "remaining": 75000,
        "utilization_pct": 85
      },
      "channel_allocation": {
        "olv": { "committed": 275000, "pct": 55 },
        "display": { "committed": 150000, "pct": 30 }
      },
      "governed_actions": [
        {
          "governance_context": "gc_mb_seller_456",
          "purchase_type": "media_buy",
          "status": "active",
          "committed": 275000,
          "check_count": 8
        },
        {
          "governance_context": "gc_mb_seller_789",
          "purchase_type": "media_buy",
          "status": "active",
          "committed": 150000,
          "check_count": 7
        },
        {
          "governance_context": "gc_rights_acme_img",
          "purchase_type": "rights_license",
          "status": "active",
          "committed": 75000,
          "check_count": 2
        }
      ],
      "summary": {
        "checks_performed": 14,
        "outcomes_reported": 12,
        "statuses": {
          "approved": 12,
          "denied": 1,
          "conditions": 1,
          "human_reviewed": 1  // also counted in approved or denied above; never counted in conditions (an agent-issued flow-control state, not a human resolution)
        },
        "findings_count": 2,
        "escalations": [
          {
            "check_id": "chk_esc_001",
            "reason": "Budget reallocation exceeds threshold",
            "resolution": "approved_by_human",
            "resolved_at": "2026-03-16T09:30:00Z"
          }
        ],
        "drift_metrics": {
          "escalation_rate": 0.07,
          "escalation_rate_trend": "stable",
          "auto_approval_rate": 0.80,
          "human_override_rate": 0.02,
          "mean_confidence": 0.88,
          "thresholds": {
            "escalation_rate_max": 0.20,
            "escalation_rate_min": 0.02,
            "auto_approval_rate_max": 0.95,
            "human_override_rate_max": 0.15
          }
        }
      },
      "entries": [
        {
          "id": "chk_001",
          "type": "check",
          "timestamp": "2026-03-10T10:05:00Z",
          "caller": "https://orchestrator.pinnacle-media.com/agent",
          "tool": "get_products",
          "check_type": "intent",
          "verdict": "approved",
          "explanation": "Product discovery within budget and channel constraints.",
          "categories_evaluated": ["budget_authority", "strategic_alignment"],
          "policies_evaluated": ["us_coppa"]
        },
        {
          "id": "chk_003",
          "type": "check",
          "timestamp": "2026-03-15T11:05:00Z",
          "caller": "https://ads.seller-example.com/adcp",
          "tool": "create_media_buy",
          "check_type": "execution",
          "mode": "enforce",
          "governance_context": "gc_mb_seller_456",
          "plan_hash": "oR0jFDEtzcwgPbNf-Ofd_fZHYfAyD1TRbzGOFBVCG-c",
          "purchase_type": "media_buy",
          "verdict": "approved",
          "explanation": "Media buy within plan budget ($150,000 of $500,000 remaining). Geo targeting matches authorized markets. COPPA compliance verified.",
          "categories_evaluated": ["budget_authority", "regulatory_compliance", "brand_policy"],
          "policies_evaluated": ["us_coppa", "alcohol_advertising"],
          "findings": [
            {
              "category_id": "budget_authority",
              "severity": "info",
              "explanation": "Budget utilization at 70% after this buy."
            }
          ]
        },
        {
          "id": "out_001",
          "type": "outcome",
          "timestamp": "2026-03-15T11:10:00Z",
          "caller": "https://orchestrator.pinnacle-media.com/agent",
          "governance_context": "gc_mb_seller_456",
          "purchase_type": "media_buy",
          "outcome": "completed",
          "committed_budget": 150000
        },
        {
          "id": "out_del_001",
          "type": "outcome",
          "timestamp": "2026-03-22T00:00:00Z",
          "caller": "https://ads.seller-example.com/adcp",
          "governance_context": "gc_mb_seller_456",
          "purchase_type": "media_buy",
          "outcome": "delivery",
          "outcome_status": "accepted"
        }
      ]
    }
  ]
}
```

## Fields

### Request

| Field | Type | Required | Description |
| - | - | - | - |
| `plan_ids` | string\[] | At least one of `plan_ids`, `portfolio_plan_ids`, or `governance_contexts` | Plan IDs to retrieve. |
| `portfolio_plan_ids` | string\[] | At least one of `plan_ids`, `portfolio_plan_ids`, or `governance_contexts` | Portfolio plan IDs. Expanded to member plans. |
| `governance_contexts` | string\[] | No | Filter results to specific governed actions by their `governance_context` values. When present, only entries and summaries for the matching governed actions are returned. |
| `purchase_types` | string\[] | No | Filter results by purchase type (e.g., `["rights_license"]` to see all rights activity). When present, only entries and summaries matching these purchase types are returned. |
| `include_entries` | boolean | No | Include the full audit trail. Default: `false`. |

### Response

| Field | Type | Description |
| - | - | - |
| `plans` | array | Audit data for each requested plan. |
| `plans[].plan_id` | string | Plan identifier. |
| `plans[].plan_version` | number | Current plan version. |
| `plans[].status` | enum | `active`, `suspended`, or `completed`. |
| `plans[].budget` | object | Budget state. |
| `plans[].budget.authorized` | number | Total authorized budget from the plan. |
| `plans[].budget.committed` | number | Total budget committed from confirmed outcomes. |
| `plans[].budget.remaining` | number | Authorized minus committed. |
| `plans[].budget.utilization_pct` | number | Committed as a percentage of authorized. |
| `plans[].channel_allocation` | object | Current channel mix. Keyed by channel ID. |
| `plans[].channel_allocation[channel].committed` | number | Budget committed to this channel. |
| `plans[].channel_allocation[channel].pct` | number | Channel's share of the authorized total budget. |
| `plans[].governed_actions` | array | Per-governed-action breakdown, grouped by `governance_context`. |
| `plans[].governed_actions[].governance_context` | string | Opaque governance context identifying this governed action. |
| `plans[].governed_actions[].purchase_type` | enum | `media_buy`, `rights_license`, `signal_activation`, or `creative_services`. |
| `plans[].governed_actions[].status` | enum | `active`, `suspended`, or `completed`. |
| `plans[].governed_actions[].committed` | number | Budget committed for this governed action. |
| `plans[].governed_actions[].check_count` | integer | Number of governance checks performed. |
| `plans[].summary` | object | Aggregate validation and outcome statistics. |
| `plans[].summary.checks_performed` | number | Total governance checks performed. |
| `plans[].summary.outcomes_reported` | number | Total outcomes reported. |
| `plans[].summary.statuses` | object | Count of each governance check status (`approved`, `denied`, `conditions`). Also includes `human_reviewed` as a supplementary count — checks that required human review before resolving. Always a subset of `approved` + `denied`; `conditions` is an agent-issued flow-control state and is never counted here. |
| `plans[].summary.findings_count` | number | Total findings across all checks and outcomes. |
| `plans[].summary.escalations` | array | Checks that were escalated for human review and their resolutions. |
| `plans[].summary.escalations[].check_id` | string | The governance check that was escalated. |
| `plans[].summary.escalations[].reason` | string | Why the check was escalated. |
| `plans[].summary.escalations[].resolution` | string | How it was resolved (e.g., `approved_by_human`, `rejected_by_human`). |
| `plans[].summary.escalations[].resolved_at` | string | ISO 8601 resolution timestamp. |
| `plans[].summary.drift_metrics` | object | Aggregate governance metrics for detecting oversight drift. See [specification](/dist/docs/3.1.0-rc.7/governance/campaign/specification#drift-detection). |
| `plans[].summary.drift_metrics.escalation_rate` | number | Fraction of checks that were escalated for human review (0-1). |
| `plans[].summary.drift_metrics.escalation_rate_trend` | enum | `increasing`, `stable`, or `declining`. |
| `plans[].summary.drift_metrics.auto_approval_rate` | number | Fraction of checks approved without human intervention (0-1). |
| `plans[].summary.drift_metrics.human_override_rate` | number | Fraction of escalations where the human overrode the governance agent's recommendation (0-1). |
| `plans[].summary.drift_metrics.mean_confidence` | number | Average confidence score across findings (0-1). Present when findings include confidence. |
| `plans[].summary.drift_metrics.thresholds` | object | Organization-defined thresholds for drift metrics. When a metric crosses its threshold, the governance agent includes a finding. |
| `plans[].summary.drift_metrics.thresholds.escalation_rate_max` | number | Maximum acceptable escalation rate. A rate above this may indicate policy miscalibration. |
| `plans[].summary.drift_metrics.thresholds.escalation_rate_min` | number | Minimum acceptable escalation rate. A rate below this may indicate eroding oversight. |
| `plans[].summary.drift_metrics.thresholds.auto_approval_rate_max` | number | Maximum acceptable auto-approval rate. |
| `plans[].summary.drift_metrics.thresholds.human_override_rate_max` | number | Maximum acceptable human override rate. |
| `plans[].entries` | array | Ordered audit trail (only when `include_entries` is `true`). |
| `plans[].entries[].id` | string | Entry identifier. |
| `plans[].entries[].type` | enum | `check` or `outcome`. |
| `plans[].entries[].timestamp` | string | ISO 8601 timestamp. |
| `plans[].entries[].plan_id` | string | Plan this entry belongs to. Present when querying multiple plans or a portfolio. |
| `plans[].entries[].caller` | string | URL of the agent that made the request. Resolved from the credentials used on the governance callback. |
| `plans[].entries[].tool` | string | The AdCP tool (present for `check` entries). |
| `plans[].entries[].status` | enum | Governance check status (present for `check` entries). |
| `plans[].entries[].check_type` | enum | `intent` or `execution` (present for `check` entries). Inferred from the fields present on the original check request. |
| `plans[].entries[].mode` | enum | `audit`, `advisory`, or `enforce` — governance mode active when this check was evaluated. Recorded by the governance agent from its runtime configuration at check time, not from a plan field. Present on check entries; absent on outcome entries and on governance agents that have not yet adopted this field. Lets auditors distinguish `approved` decisions made under `enforce` from those made under `audit` (where the agent could not have blocked anything). |
| `plans[].entries[].explanation` | string | Human-readable explanation of the governance decision (present for `check` entries). |
| `plans[].entries[].policies_evaluated` | array | Registry policy IDs evaluated during this check. |
| `plans[].entries[].categories_evaluated` | array | Governance categories evaluated (e.g., `budget_authority`, `regulatory_compliance`). **Agent-internal labels**, not a protocol-level enum — each string is defined by the governance agent's policy model. Since one governance agent per account composes all specialist review (legal, brand safety, category-specialist reviewers) behind its single endpoint, `categories_evaluated` and `findings[].details` are how internal decomposition surfaces for audit. Consumers MUST treat values as opaque labels: pattern-matching against a fixed list is not safe across agents. |
| `plans[].entries[].findings` | array | Findings from this check, including category, severity, policy ID, explanation, and confidence. |
| `plans[].entries[].governance_context` | string | Opaque governance context identifying the governed action this entry belongs to. |
| `plans[].entries[].plan_hash` | string | Audit-layer binding to the plan revision this attestation was evaluated over — `base64url_no_pad(SHA-256(JCS(plan_payload)))` per [Plan binding and audit](/dist/docs/3.1.0-rc.7/governance/campaign/specification#plan-binding-and-audit). Present on `check` entries. Auditors and buyer-side compliance tooling verify by recomputing over the retained plan revision and byte-comparing the decoded 32-byte digests. |
| `plans[].entries[].purchase_type` | enum | `media_buy`, `rights_license`, `signal_activation`, or `creative_services`. Present when the entry is associated with a specific governed action. |
| `plans[].entries[].outcome` | enum | Outcome type (present for `outcome` entries). |
| `plans[].entries[].committed_budget` | number | Budget committed (present for `completed` outcome entries). |
| `plans[].entries[].outcome_status` | string | Outcome status (present for `outcome` entries). |

## Authorization

The request schema does not carry an envelope `account` field — tenant identity is resolved from the submitted IDs. The governance agent MUST verify that the authenticated principal is authorized for every `plan_ids` member, every plan expanded from `portfolio_plan_ids`, and every governed action addressed by `governance_contexts`. When any element fails the authorization check the governance agent MUST fail closed with a generic `PLAN_NOT_FOUND` response — the error body MUST NOT distinguish "unauthorized" from "not found" or name the offending ID. See [Agent and Account Isolation](/dist/docs/3.1.0-rc.7/building/by-layer/L1/security#agent-and-account-isolation) for the pattern and existence-leak guardrails.

## Error codes

| Code | Recovery | Description |
| - | - | - |
| `PLAN_NOT_FOUND` | correctable | No plan with this ID, or the authenticated principal is not authorized for it. The two cases MUST be indistinguishable in the response to prevent plan-ID enumeration. |

## Related tasks

* [`sync_plans`](./sync_plans) -- Push or update plans
* [`check_governance`](./check_governance) -- Validate actions against the plan
* [`report_plan_outcome`](./report_plan_outcome) -- Report outcomes to update plan state