Skip to main content

​
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": 15,
        "outcomes_reported": 12,
        "statuses": {
          "approved": 12,
          "denied": 1,
          "conditions": 1,
          "human_reviewed": 1  // supplementary: subset of approved + denied that went through internal human review
        },
        "findings_count": 2,
        "human_reviews": [
          {
            "check_id": "chk_esc_001",
            "reason": "Budget reallocation exceeds threshold",
            "resolution": "approved_by_human",
            "resolved_at": "2026-03-16T09:30:00Z"
          }
        ],
        "drift_metrics": {
          "human_review_rate": 0.07,
          "human_review_rate_trend": "stable",
          "auto_approval_rate": 0.80,
          "human_override_rate": 0.02,
          "mean_confidence": 0.88,
          "thresholds": {
            "human_review_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",
          "status": "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",
          "status": "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

FieldTypeRequiredDescription
plan_idsstring[]At least one of plan_ids, portfolio_plan_ids, or governance_contextsPlan IDs to retrieve.
portfolio_plan_idsstring[]At least one of plan_ids, portfolio_plan_ids, or governance_contextsPortfolio plan IDs. Expanded to member plans.
governance_contextsstring[]NoFilter results to specific governed actions by their governance_context values. When present, only entries and summaries for the matching governed actions are returned.
purchase_typesstring[]NoFilter 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_entriesbooleanNoInclude the full audit trail. Default: false.

​
Response

FieldTypeDescription
plansarrayAudit data for each requested plan.
plans[].plan_idstringPlan identifier.
plans[].plan_versionnumberCurrent plan version.
plans[].statusenumactive, suspended, or completed.
plans[].budgetobjectBudget state.
plans[].budget.authorizednumberTotal authorized budget from the plan.
plans[].budget.committednumberTotal budget committed from confirmed outcomes.
plans[].budget.remainingnumberAuthorized minus committed.
plans[].budget.utilization_pctnumberCommitted as a percentage of authorized.
plans[].channel_allocationobjectCurrent channel mix. Keyed by channel ID.
plans[].channel_allocation[channel].committednumberBudget committed to this channel.
plans[].channel_allocation[channel].pctnumberChannel’s share of the authorized total budget.
plans[].governed_actionsarrayPer-governed-action breakdown, grouped by governance_context.
plans[].governed_actions[].governance_contextstringOpaque governance context identifying this governed action.
plans[].governed_actions[].purchase_typeenummedia_buy, rights_license, signal_activation, or creative_services.
plans[].governed_actions[].statusenumactive, suspended, or completed.
plans[].governed_actions[].committednumberBudget committed for this governed action.
plans[].governed_actions[].check_countintegerNumber of governance checks performed.
plans[].summaryobjectAggregate validation and outcome statistics.
plans[].summary.checks_performednumberTotal governance checks performed.
plans[].summary.outcomes_reportednumberTotal outcomes reported.
plans[].summary.statusesobjectCount of each governance check status (approved, denied, conditions). Also includes human_reviewed as a supplementary count — a subset of approved + denied that went through internal human review before resolving.
plans[].summary.findings_countnumberTotal findings across all checks and outcomes.
plans[].summary.human_reviewsarrayChecks that required internal human review and their resolutions.
plans[].summary.human_reviews[].check_idstringThe governance check that required human review.
plans[].summary.human_reviews[].reasonstringWhy human review was required.
plans[].summary.human_reviews[].resolutionstringHow it was resolved (e.g., approved_by_human, rejected_by_human).
plans[].summary.human_reviews[].resolved_atstringISO 8601 resolution timestamp.
plans[].summary.drift_metricsobjectAggregate governance metrics for detecting oversight drift. See specification.
plans[].summary.drift_metrics.human_review_ratenumberFraction of checks that required internal human review (0-1).
plans[].summary.drift_metrics.human_review_rate_trendenumincreasing, stable, or declining.
plans[].summary.drift_metrics.auto_approval_ratenumberFraction of checks approved without human intervention (0-1).
plans[].summary.drift_metrics.human_override_ratenumberFraction of human reviews where the human overrode the agent (0-1).
plans[].summary.drift_metrics.mean_confidencenumberAverage confidence score across findings (0-1). Present when findings include confidence.
plans[].summary.drift_metrics.thresholdsobjectOrganization-defined thresholds for drift metrics. When a metric crosses its threshold, the governance agent includes a finding.
plans[].summary.drift_metrics.thresholds.human_review_rate_maxnumberMaximum acceptable human review rate.
plans[].summary.drift_metrics.thresholds.human_review_rate_minnumberMinimum acceptable human review rate. A rate below this may indicate eroding oversight.
plans[].summary.drift_metrics.thresholds.auto_approval_rate_maxnumberMaximum acceptable auto-approval rate.
plans[].summary.drift_metrics.thresholds.human_override_rate_maxnumberMaximum acceptable human override rate.
plans[].entriesarrayOrdered audit trail (only when include_entries is true).
plans[].entries[].idstringEntry identifier.
plans[].entries[].typeenumcheck or outcome.
plans[].entries[].timestampstringISO 8601 timestamp.
plans[].entries[].plan_idstringPlan this entry belongs to. Present when querying multiple plans or a portfolio.
plans[].entries[].callerstringURL of the agent that made the request. Resolved from the credentials used on the governance callback.
plans[].entries[].toolstringThe AdCP tool (present for check entries).
plans[].entries[].statusenumGovernance check status (present for check entries).
plans[].entries[].check_typeenumintent or execution (present for check entries). Inferred from the fields present on the original check request.
plans[].entries[].modeenumaudit, 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[].explanationstringHuman-readable explanation of the governance decision (present for check entries).
plans[].entries[].policies_evaluatedarrayRegistry policy IDs evaluated during this check.
plans[].entries[].categories_evaluatedarrayGovernance categories evaluated (e.g., budget_authority, regulatory_compliance).
plans[].entries[].findingsarrayFindings from this check, including category, severity, policy ID, explanation, and confidence.
plans[].entries[].governance_contextstringOpaque governance context identifying the governed action this entry belongs to.
plans[].entries[].plan_hashstringAudit-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_typeenummedia_buy, rights_license, signal_activation, or creative_services. Present when the entry is associated with a specific governed action.
plans[].entries[].outcomeenumOutcome type (present for outcome entries).
plans[].entries[].committed_budgetnumberBudget committed (present for completed outcome entries).
plans[].entries[].outcome_statusstringOutcome 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

CodeRecoveryDescription
PLAN_NOT_FOUNDcorrectableNo 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.