Capture Official Price Page Drift Before AI API Workbooks Ship

AI API cost workbooks drift faster than most teams expect.

The workbook starts as a useful bridge between engineering, finance, and procurement. It has a model column, input token assumptions, output token assumptions, cache-hit assumptions, a route owner, and a projected monthly cost. Then one upstream page changes. A gateway normalizes a new route. A billing group multiplier is clarified. An old model alias stays in one sheet tab because nobody touched that tab during the last release.

Nothing breaks at compile time.

The broken part appears later, usually in a budget review or incident review, when someone asks why the shipped SDK example, the workbook estimate, and the runtime ledger all disagree.

For Tier 1 and Tier 2 teams, the answer cannot be "the spreadsheet was probably close enough." The answer should be a receipt:

• which pricing source was checked;
• when it was checked;
• which exact model rows entered the workbook;
• whether the workbook shows base rates or effective account rates;
• who approved a meaningful change;
• and which release consumed that approved snapshot.

This article shows a compact drift-capture pattern for AI API pricing workbooks. The examples use AIWave's public pricing endpoints because they are date-stamped and OpenAI-compatible gateway oriented, but the pattern applies to any multi-model API gateway or internal platform.

For this article, I rechecked the public AIWave pricing endpoints on September 15, 2026. The static endpoint at https://aiwave.live/api/v1/pricing returned 64 model rows, checked: 2026-09-10, updated_at: 2026-09-10, and a pricing version. The dynamic endpoint at https://aiwave.live/api/pricing returned 64 route rows and current group ratios of default: 1 and vip: 0.9. Treat those as source facts with dates, not evergreen copy.

The workbook should not be the source of record

A workbook is a decision surface. It is not the source of record.

That distinction matters. A workbook often has scenario columns, finance assumptions, annualized projections, currency preferences, and team-specific workload estimates. Those fields are useful, but they are not the same thing as the published pricing row or the runtime route table.

Keep three layers separate:

1. Source facts: the public pricing endpoint, official provider page, route table, or approved internal export.
2. Workbook assumptions: workload size, cache-hit assumption, retry policy, billing view, currency conversion date, and owner.
3. Runtime receipts: the actual model, account group, token counts, cache behavior, retry count, and final billed result.

When teams collapse those layers into one sheet, every discussion becomes ambiguous. Did the model price change, or did the scenario change? Did the default rate change, or did someone apply a VIP key multiplier? Did the runtime call hit cache, or did the workbook assume cache?

The drift-capture job should update source facts. It should not silently rewrite business assumptions.

Capture a snapshot before the workbook opens

Start with a small snapshot command. It fetches the pricing source, records the source dates, and stores a content fingerprint. It does not need API credentials if the pricing source is public.

import hashlib
import json
import urllib.request
from datetime import datetime, timezone
from pathlib import Path


PRICING_URL = "https://aiwave.live/api/v1/pricing"


def fetch_json(url: str) -> tuple[dict, bytes]:
    request = urllib.request.Request(
        url,
        headers={"User-Agent": "pricing-drift-capture/1.0"},
    )
    with urllib.request.urlopen(request, timeout=20) as response:
        raw = response.read()
    return json.loads(raw.decode("utf-8")), raw


def model_rows(payload: dict) -> list[dict]:
    return payload.get("models") or payload.get("data") or []


payload, raw = fetch_json(PRICING_URL)
snapshot = {
    "captured_at": datetime.now(timezone.utc).isoformat(),
    "pricing_source": PRICING_URL,
    "pricing_checked": payload.get("checked"),
    "pricing_updated_at": payload.get("updated_at"),
    "pricing_version": payload.get("pricing_version"),
    "content_sha256": hashlib.sha256(raw).hexdigest(),
    "row_count": len(model_rows(payload)),
    "models": model_rows(payload),
}

Path("pricing-snapshot.json").write_text(
    json.dumps(snapshot, indent=2, sort_keys=True),
    encoding="utf-8",
)

That file is boring in the best possible way. It gives reviewers one artifact to diff. It also makes the workbook reproducible. If someone asks what the workbook believed on release day, the answer is in a JSON file, not in a tab that may have been edited later.

Normalize only the fields the workbook needs

The next step is not to copy every provider-specific field into a spreadsheet. Normalize only what the workbook needs for its estimates and reviews.

A compact normalized row can look like this:

{
  "model": "deepseek-v4-pro",
  "provider": "DeepSeek",
  "unit": "per_1m_text_tokens",
  "input_usd_per_1m_tokens": 1.914,
  "cache_hit_usd_per_1m_tokens": 0.0637362,
  "output_usd_per_1m_tokens": 5.742,
  "effective_date": "2026-08-27",
  "pricing_checked": "2026-09-10",
  "billing_view": "base_default_rate"
}

The important field is billing_view.

If the workbook shows base default rates, say that. If it shows effective account rates, say that instead and include the multiplier source. A discount, negotiated group, or account-specific setting should never be mixed into a base pricing table without a label.

AIWave's current public base price view is default 1. A VIP key may use 0.9 where the application and account configuration allow it. A workbook can show both, but it should not let a reader confuse one for the other.

Compare against the last approved snapshot

A nightly job can fetch pricing every day. It should not automatically push every change into finance workbooks.

Instead, compare the new snapshot against the last approved snapshot and classify the diff.

from dataclasses import dataclass


PRICE_FIELDS = (
    "input_usd_per_1m_tokens",
    "cache_hit_usd_per_1m_tokens",
    "output_usd_per_1m_tokens",
)


@dataclass
class Drift:
    code: str
    model: str
    field: str
    before: object
    after: object


def index_by_model(rows: list[dict]) -> dict[str, dict]:
    return {row["model"]: row for row in rows if row.get("model")}


def compare_snapshots(before_rows: list[dict], after_rows: list[dict]) -> list[Drift]:
    before = index_by_model(before_rows)
    after = index_by_model(after_rows)
    drifts: list[Drift] = []

    for model in sorted(set(before) | set(after)):
        if model not in before:
            drifts.append(Drift("model_added", model, "", None, after[model]))
            continue
        if model not in after:
            drifts.append(Drift("model_removed", model, "", before[model], None))
            continue

        for field in PRICE_FIELDS:
            if before[model].get(field) != after[model].get(field):
                drifts.append(
                    Drift(
                        "price_field_changed",
                        model,
                        field,
                        before[model].get(field),
                        after[model].get(field),
                    )
                )

        if before[model].get("effective_date") != after[model].get("effective_date"):
            drifts.append(
                Drift(
                    "effective_date_changed",
                    model,
                    "effective_date",
                    before[model].get("effective_date"),
                    after[model].get("effective_date"),
                )
            )

    return drifts

Do not treat every diff as a release blocker. A new model row may simply be catalog growth. A changed effective date may require human review. A missing route used by an SDK example should block the release until a fallback or deprecation note is approved.

The useful categories are simple:

• Informational: new row, metadata clarification, provider display-name change.
• Review required: price field changed, effective date changed, billing multiplier changed.
• Blocking: workbook references a removed model, unsupported endpoint, missing billing view, or stale source date.

That classification lets finance and engineering work from the same evidence without making every nightly change an emergency.

Write back with an approval receipt

The workbook update should be a deliberate action. It can be automated, but it should still leave a receipt.

{
  "receipt_type": "pricing_workbook_update",
  "approved_at": "2026-09-15T02:18:00Z",
  "pricing_source": "https://aiwave.live/api/v1/pricing",
  "pricing_checked": "2026-09-10",
  "pricing_version": "8c7a0c0b30661ccbc13d142cb54d1e4ae445fe774b2c6fa501080db97c7a3e56",
  "billing_view": "base_default_rate",
  "row_count": 64,
  "changed_models": ["deepseek-flash"],
  "reviewer": "platform-owner",
  "workbook": "ai-api-cost-model.xlsx"
}

That receipt is safe to store in a repo or CI artifact if it contains no credentials, request bodies, customer identifiers, or private account state. It should say what changed and why the workbook was allowed to consume it.

If your workbook includes effective account rates, add the multiplier source:

{
  "billing_view": "effective_account_rate",
  "group_ratio_source": "https://aiwave.live/api/pricing",
  "group_ratio_checked_at": "2026-09-15T02:18:00Z",
  "group_ratio": {
    "default": 1,
    "vip": 0.9
  }
}

Keep the base-rate receipt and the effective-rate receipt separate. That separation saves hours during procurement review.

Add a workbook contract test

Once the workbook consumes a snapshot, add a small contract test around the export.

The test should fail when the workbook:

• references a model that is missing from the approved snapshot;
• uses a price row without effective_date;
• omits pricing_source;
• omits billing_view;
• mixes base and effective account rates in one unlabeled column;
• or ships with a snapshot older than your review window.

Here is a minimal CSV-oriented version:

import csv
import json
from pathlib import Path


REQUIRED_COLUMNS = {
    "model",
    "pricing_source",
    "pricing_checked",
    "effective_date",
    "billing_view",
    "input_usd_per_1m_tokens",
    "output_usd_per_1m_tokens",
}


def load_snapshot_models(path: str) -> set[str]:
    snapshot = json.loads(Path(path).read_text(encoding="utf-8"))
    return {
        row["model"]
        for row in snapshot["models"]
        if row.get("model")
    }


def check_workbook_export(csv_path: str, snapshot_path: str) -> list[str]:
    approved_models = load_snapshot_models(snapshot_path)
    failures: list[str] = []

    with open(csv_path, newline="", encoding="utf-8") as handle:
        reader = csv.DictReader(handle)
        missing = REQUIRED_COLUMNS - set(reader.fieldnames or [])
        if missing:
            failures.append(f"missing columns: {sorted(missing)}")
            return failures

        billing_views = set()
        for row_number, row in enumerate(reader, start=2):
            model = row["model"]
            billing_views.add(row["billing_view"])

            if model not in approved_models:
                failures.append(f"row {row_number}: unknown model {model}")
            if not row["effective_date"]:
                failures.append(f"row {row_number}: missing effective date")
            if not row["pricing_checked"]:
                failures.append(f"row {row_number}: missing pricing checked date")

        if len(billing_views) > 1:
            failures.append("mixed billing views require separate labeled sections")

    return failures

That test is intentionally narrow. It does not calculate your whole forecast. It only checks whether the workbook can defend its source facts.

Decide what should block a release

Not every workbook issue deserves the same response.

Use a release rule that engineers and finance can both understand:

An AI API cost workbook may ship only when:
1. every model row comes from an approved dated snapshot,
2. the pricing source and pricing version are recorded,
3. base rates and effective account rates are labeled separately,
4. source drift above the review threshold has an approval receipt,
5. and the runtime SDK examples point to the same billing view.

That last point is easy to miss. A workbook can be correct while the README is stale. A README can be correct while the demo notebook still has an old route name. External docs, SDK examples, notebooks, and procurement sheets should all point to the same pricing source and billing view.

The release gate does not need private business data. It does not need real API keys. It does not need customer examples. It needs dated public facts, explicit assumptions, and a receipt trail.

Keep source drift separate from runtime variance

Source drift and runtime variance are different failures.

Source drift means the workbook used stale or unlabeled pricing facts. Runtime variance means the actual run had different token counts, cache behavior, retry behavior, model resolution, or account group than the estimate assumed.

Do not solve both with one giant spreadsheet. Capture pricing drift before the workbook updates. Capture runtime variance in request-level receipts after calls execute.

Then join the two only during review:

• The workbook explains the expected route and budget.
• The pricing snapshot explains the source facts.
• The runtime receipt explains what actually happened.
• The variance review explains whether the policy, implementation, or estimate should change.

That workflow is slower than pasting a new row into a sheet. It is also much easier to trust.

A practical rollout path

If your team already has a pricing workbook, do not rebuild it first.

Start with a snapshot file and one contract test. Add pricing_source, pricing_checked, effective_date, and billing_view to the rows that feed production SDK examples. Run the test in warning mode for one week.

Next, add a nightly drift job. Let it open a review item when the public source changes, but do not let it rewrite scenarios by itself. Humans should decide whether a change affects active estimates, docs, demos, or only future catalog exploration.

Finally, require an approval receipt before any release that changes model price assumptions or billing-group assumptions.

The goal is not to make workbooks fancy. The goal is to make them answerable.

When a buyer asks why a number changed, you should be able to point to a source URL, a date, a version, a diff, and a receipt. That is the difference between a spreadsheet and an operational contract.