Introduction

Why integrate SAP

• Standardizes AI usage tracking across models and providers — one event format, one aggregation model
• Provides immediate usage analytics without building custom pipelines
• Enables optional user-facing transparency via the SAP button ("the missing button") — builds user trust
• Creates a foundation for cost optimization, efficiency feedback, and future compliance tooling
• Minimal integration cost — one API call per inference, fire-and-forget, never blocks your app

Quick start

The simplest integration is a single API call after each AI inference. This example uses the Supabase RPC endpoint that SAP runs on:

// After your AI call completes, fire and forget:
fetch('https://fpnpfnahwaztdlxuayyv.supabase.co/rest/v1/rpc/track_sap_event', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': YOUR_SUPABASE_ANON_KEY,
    'Authorization': `Bearer ${YOUR_SUPABASE_ANON_KEY}`
  },
  body: JSON.stringify({
    p_source: 'external',
    p_model: 'anthropic/claude-sonnet-4',
    p_prompt_tokens: 450,
    p_completion_tokens: 820,
    p_kwh: 0.00076,
    p_co2_g: 0.38,
    p_water_ml: 1.37
  })
});

That's it. One call per inference. The call is designed to be fire-and-forget and should never block your application or user experience. The backend atomically updates global, daily, and hourly rollups. No additional setup required.

If you don't want to calculate energy estimates yourself, you can omit p_kwh, p_co2_g, and p_water_ml — the database function uses sensible defaults (0.0004 kWh, 0.2g CO₂, 0.72 mL water).

Event schema

Each AI inference produces one row in the sap_events table:

API

SAP uses Supabase RPC and REST endpoints.

Track an event

POST /rest/v1/rpc/track_sap_event

Records a single inference event and atomically updates all aggregation tables. Returns the event UUID.

Headers required: apikey (Supabase anon key), Authorization: Bearer {key}, Content-Type: application/json.

Read global stats

GET /rest/v1/global_stats?select=*&id=eq.1

Returns a single row: total_count, total_kwh, total_co2, total_water, sap_tracked_count.

Read personal stats

GET /rest/v1/sap_my_stats?select=*&user_id=eq.{id}

Requires user JWT. Returns: total_events, total_kwh, total_co2_g, total_water_ml, per-source breakdown, avg_tokens, date range.

Energy estimates

SAP uses model-specific coefficients to estimate energy per inference. These are based on published benchmarks (Patterson et al. 2021, ML CO2 Impact, MLCommons estimates) and are conservative.

Model coefficients

Base kWh per ~1000-token inference:

Scaling

kwh = base_coefficient * clamp(total_tokens / 1000, 0.5, 4.0)

Derived metrics

Water estimates represent cooling usage based on evaporative data center systems and are directional, not exact. Not all data centers use evaporative cooling — some use closed-loop or air cooling systems that consume significantly less water.

Aggregation

Aggregation is handled entirely server-side. Clients only send events. Every call to track_sap_event atomically updates three aggregation layers:

• Global — single row in global_stats, tracks totals across all users and sources
• Daily — one row per day in sap_daily_stats
• Hourly — one row per date + hour in sap_hourly_stats

Personal stats are computed on read via the sap_my_stats view, which aggregates all events for a given user_id with per-source breakdowns.

Backend integration

Backend-only integration is the primary pattern. No UI required. Call the API after each inference.

TypeScript

import { trackSapEvent, estimateKwh } from '@/lib/sap';

// After your AI call:
trackSapEvent({
  userId: user?.id,
  source: 'external',
  model: 'anthropic/claude-sonnet-4',
  promptTokens: 450,
  completionTokens: 820,
});

The trackSapEvent function is fire-and-forget — it calculates energy estimates, sends the event, and never throws. It won't block your application or surface errors to users.

Python

import requests, threading

def track_sap_event(model, prompt_tokens, completion_tokens, source="external"):
    total = prompt_tokens + completion_tokens
    kwh = 0.0004 * max(0.5, min(4, total / 1000))

    def _send():
        try:
            requests.post(
                "https://fpnpfnahwaztdlxuayyv.supabase.co/rest/v1/rpc/track_sap_event",
                json={
                    "p_source": source, "p_model": model,
                    "p_prompt_tokens": prompt_tokens,
                    "p_completion_tokens": completion_tokens,
                    "p_kwh": kwh, "p_co2_g": kwh * 500,
                    "p_water_ml": kwh * 1800,
                },
                headers={
                    "apikey": ANON_KEY,
                    "Authorization": f"Bearer {ANON_KEY}",
                    "Content-Type": "application/json",
                },
                timeout=5,
            )
        except: pass

    threading.Thread(target=_send).start()

Any language

SAP is just a POST to a REST endpoint. Any language that can make HTTP requests can integrate. The pattern is always the same: after your AI call completes, fire off the tracking call in the background.

Frontend integration

For browser-based apps, SAP provides a session tracking module that generates a per-tab session ID, maintains a counter, and lets UI components subscribe to tracking events.

import { getSapSessionCount, onSapTrack } from '@/lib/sap';

const [count, setCount] = useState(getSapSessionCount());

useEffect(() => {
  return onSapTrack((n) => setCount(n));
}, []);

The session ID persists for the lifetime of the browser tab. When a user authenticates, all session activity can be attributed to their account, enabling persistent personal usage tracking over time. Anonymous usage works instantly; login enhances it.

Optional UI

The core of SAP is backend measurement. The UI is optional but encouraged — it gives end users visibility into their AI usage, which most interfaces don't provide. It can be embedded, customized, or omitted entirely depending on the application.

The reference implementation is a small button that sits in the chat interface. It shows a session generation count. Clicking it opens a dashboard popup with personal and global stats. The button spins briefly each time an inference is tracked — a subtle signal that measurement is happening.

This is sometimes called "the missing button" — a piece of UI that arguably should exist in every AI chat interface but currently doesn't.

This is not required for integration. Most apps integrate SAP backend-only. The UI is for apps that want to give users visibility.

Reference UI (optional) — try it

0

0 interactions tracked

I just prompted AI

Energy: 0 kWh  ·  CO₂: 0g  ·  Water: 0 mL

Click "I just prompted AI" to simulate a tracked inference. Click the SAP button to open the dashboard popup — the same experience users would see in a real integration.

For non-React apps, an embeddable script is available:

<!-- Auto-attaches to prompt inputs, adds SAP button -->
<script src="https://phewsh.com/SustainableAiProtocol/sap-embed.js"></script>

Status

Live

• Tracking real AI inference usage in production (PHEWSH Intent Engine, PHEWSH CLI)
• Model-specific energy coefficients for 12+ models
• Per-inference token counting (input + output)
• Global + personal + daily + hourly aggregation
• Supabase RPC API — open to external integrations
• Anonymous and authenticated tracking

In progress

• Personal dashboard (usage over time)
• Embeddable widget for third-party apps
• Usage budgeting (daily/monthly limits)
• Efficiency feedback per prompt

Future

• Region-specific carbon intensity (beyond US grid average)
• Research partnerships for coefficient validation
• Data center partnerships for verified telemetry
• Compute abstraction layer (beyond AI workloads)

SAP is open source. View on GitHub · Contact · A PHEWSH open standard.