Meter-only mode

1. When to use it

• You handle PHI, PII, secrets, or source code that cannot leave your environment.
• You already have an OpenAI / Anthropic / Gemini integration and don't want to add a router.
• You want CFO-grade attribution and budgets without changing how requests are made.

2. The contract

POST /api/v2/meter/events accepts the economic event and rejects any prompt / response / content / file / message / chat_history field with INVALID_INPUT. There is no path that persists raw content via this endpoint. Privacy posture is resolved server-side; the response tells you what was stored.

3. Minimum payload

POST /api/v2/meter/events
Authorization: Bearer p402_live_...
Content-Type: application/json

{
  "request_id": "req_abc123",
  "source": "meter_only",
  "attribution": {
    "department_id": "claims",
    "employee_id":   "emp_42",
    "action_type":   "claims_summary",
    "workflow_id":   "prior_authorization"
  },
  "model": {
    "provider":   "google",
    "model_used": "gemini-2.0-flash"
  },
  "usage": {
    "input_tokens":  2140,
    "output_tokens": 801,
    "cost_usd":      0.0041,
    "latency_ms":    720,
    "cache_hit":     false
  },
  "governance": {
    "budget_id": "bud_claims_q2",
    "decision":  "approved"
  },
  "outcome": {
    "status":        "accepted",
    "quality_score": 0.91
  }
}

4. Response

200 OK

{
  "ok": true,
  "event_id":   "evt_...",
  "request_id": "req_abc123",
  "privacy": {
    "mode":                "metadata_only",
    "source":               "tenant_default",
    "prompt_stored":        false,
    "response_stored":      false,
    "redaction_applied":    false,
    "retention_expires_at": "2026-07-04T00:00:00.000Z"
  }
}

5. What NOT to send

The endpoint hard-rejects any of these top-level fields. The error includes the offending name so misconfigured SDK adapters fail loudly:

prompt, prompts, response, responses, completion,
messages, content, text, file, files,
document, documents, chat, chat_history, transcript

6. Privacy modes

Default is metadata_only. Tenant admins can change the tenant default and configure per-scope overrides at /dashboard/settings/privacy:

• metadata_only — economic metadata only. Default. CFO dashboards work today.
• fingerprint_only — HMAC fingerprints for duplicate / retry detection.
• redacted_trace — redacted samples and trace summaries (customer redacts first).
• private_gateway — gateway runs inside customer VPC; aggregates leave.
• full_trace — full prompt + response; opt-in only, retention-bound.

Per-request callers can pass privacy_mode to ratchet TIGHTER (e.g. force metadata_only for a one-off demo request). Callers cannot widen — admin-saved scope overrides are the only path that can widen the tenant default.

7. Outcomes

Report what happened to a request so Optimize can compute cost per accepted output, retry waste, and quality-adjusted recommendations:

POST /api/v2/outcomes

{
  "request_id":    "req_abc123",
  "status":        "accepted",
  "quality_score": 0.91
}

8. Reading events back

• GET /api/v2/meter/events — paged list, filters by privacy_mode, owner, model, provider, evidence status.
• GET /api/v2/meter/events/{id} — single event with full privacy posture.
• /dashboard/meter/events renders both with row → detail navigation.

9. Evidence bundles

Every evidence bundle export (/api/v1/analytics/evidence-bundle) includes a privacy block (mode, prompt_stored, response_stored, redaction_applied, retention_expires_at, response_capture_status, fingerprint excerpts). Finance / procurement / compliance exports always show what posture governed the event.