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

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 for the full contract.

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

Request

{
  "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:

{
  "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:

{
  "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

{
  "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.
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. 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 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 — Push or update plans
• check_governance — Validate actions against the plan
• report_plan_outcome — Report outcomes to update plan state