aicostbudget · linqiang-max · Jul 28, 2026 · Jul 28, 2026
diff --git a/README.md b/README.md
@@ -1,46 +1,48 @@
-# AI API Pricing Dataset
-
-**Source-linked, machine-readable AI API pricing for cost calculators, model comparison, budget planning, and AI FinOps.**
-
-`7 providers` | `21 normalized model records` | `10 official sources` | `JSON + CSV` | `per-model history`
-
-[![Validate](https://github.com/aicostbudget/ai-api-pricing-data/actions/workflows/validate.yml/badge.svg)](https://github.com/aicostbudget/ai-api-pricing-data/actions/workflows/validate.yml)
-[![Code license: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](LICENSE-CODE)
-[![Data license: CC BY 4.0](https://img.shields.io/badge/data-CC%20BY%204.0-green.svg)](LICENSE-DATA)
-
-[Try the AI API Cost Calculator](https://aicostbudget.com/en/ai-api-cost-calculator?utm_source=github&utm_medium=referral&utm_campaign=ai_api_pricing&utm_content=header_cost_calculator)
-
-[Browse the Pricing Dataset](https://aicostbudget.com/en/ai-api-pricing-data?utm_source=github&utm_medium=referral&utm_campaign=ai_api_pricing&utm_content=header_dataset_page) |
-[Compare Model Pricing](https://aicostbudget.com/en/model-pricing-comparison?utm_source=github&utm_medium=referral&utm_campaign=ai_api_pricing&utm_content=header_model_comparison) |
-[Plan an AI Budget](https://aicostbudget.com/en/ai-budget-planner?utm_source=github&utm_medium=referral&utm_campaign=ai_api_pricing&utm_content=header_budget_planner)
-
-[View JSON API](https://aicostbudget.github.io/ai-api-pricing-data/api/v1/prices.json) |
-[Download CSV](https://aicostbudget.github.io/ai-api-pricing-data/api/v1/prices.csv)
-
-Use this dataset when you need maintained pricing records instead of ad hoc scraped snippets. Every record includes an official source and verification metadata, and unknown or insufficiently verified prices remain `null`, never `0`.
-
-- Official-source-linked pricing records
-- Standard, cached, and batch pricing where available
-- Per-model history and dated snapshots
-- Read-only static API for calculators, dashboards, and AI FinOps tools
-
-This project is maintained as an independent public dataset by [AICostBudget](https://aicostbudget.com/en/ai-api-pricing-data?utm_source=github&utm_medium=referral&utm_campaign=ai_api_pricing&utm_content=maintainer_dataset_page).
-
-Prices change frequently, so production budget decisions should always be checked against the relevant provider pricing pages. The weekly freshness workflow checks source URLs and stale `last_verified_at` values; it does not guess, infer, or overwrite prices automatically.
-
+# AI API Pricing Dataset
+
+This dataset provides AI API model pricing data for cost estimation, LLM budget planning, and model price comparison.
+
+Maintained, curated, machine-readable pricing data for major LLM and AI APIs. Prices change frequently, so production budget decisions should always be checked against the relevant provider pricing pages.
+
+[![Validate](https://github.com/aicostbudget/ai-api-pricing-data/actions/workflows/validate.yml/badge.svg)](https://github.com/aicostbudget/ai-api-pricing-data/actions/workflows/validate.yml)
+[![Code license: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](LICENSE-CODE)
+[![Data license: CC BY 4.0](https://img.shields.io/badge/data-CC%20BY%204.0-green.svg)](LICENSE-DATA)
+
+[AI API Cost Calculator](https://aicostbudget.com/en/ai-api-cost-calculator?utm_source=huggingface&utm_medium=dataset&utm_campaign=ai_api_pricing) |
+[Model Pricing Comparison](https://aicostbudget.com/en/model-pricing-comparison?utm_source=huggingface&utm_medium=dataset&utm_campaign=ai_api_pricing) |
+[AI Budget Planner](https://aicostbudget.com/en/ai-budget-planner?utm_source=huggingface&utm_medium=dataset&utm_campaign=ai_api_pricing) |
+[Download JSON](https://aicostbudget.github.io/ai-api-pricing-data/api/v1/prices.json) |
+[Download CSV](https://aicostbudget.github.io/ai-api-pricing-data/api/v1/prices.csv)
+
+This repository publishes a versioned dataset and read-only static API for AI API pricing. It is designed for developers, SaaS builders, FinOps teams, researchers, technical writers, and AI systems that need maintained pricing records instead of ad hoc scraped snippets.
+
+This project is maintained as an independent public dataset by AICostBudget. See [aicostbudget.com](https://aicostbudget.com).
+
+## Why this dataset?
+
+- Source-linked pricing records
+- Unknown or unverified values remain `null`, never `0`
+- Versioned JSON and CSV outputs
+- Per-model history files
+- Dated full snapshots
+- Read-only static API
+- Suitable for calculators, dashboards, cost analysis, and AI FinOps tooling
+
+The weekly freshness workflow checks source URLs and stale `last_verified_at` values. It does not guess, infer, or overwrite prices automatically.
+
 ## Website Tools
 
 ### AI API Cost Calculator
 
-[Estimate token usage and monthly AI API costs.](https://aicostbudget.com/en/ai-api-cost-calculator?utm_source=github&utm_medium=referral&utm_campaign=ai_api_pricing&utm_content=website_tools_cost_calculator)
+[Estimate token usage and monthly AI API costs.](https://aicostbudget.com/en/ai-api-cost-calculator?utm_source=huggingface&utm_medium=dataset&utm_campaign=ai_api_pricing)
 
 ### Model Pricing Comparison
 
-[Compare model pricing across providers.](https://aicostbudget.com/en/model-pricing-comparison?utm_source=github&utm_medium=referral&utm_campaign=ai_api_pricing&utm_content=website_tools_model_comparison)
+[Compare model pricing across providers.](https://aicostbudget.com/en/model-pricing-comparison?utm_source=huggingface&utm_medium=dataset&utm_campaign=ai_api_pricing)
 
 ### AI Budget Planner
 
-[Plan AI feature budgets for products and SaaS applications.](https://aicostbudget.com/en/ai-budget-planner?utm_source=github&utm_medium=referral&utm_campaign=ai_api_pricing&utm_content=website_tools_budget_planner)
+[Plan AI feature budgets for products and SaaS applications.](https://aicostbudget.com/en/ai-budget-planner?utm_source=huggingface&utm_medium=dataset&utm_campaign=ai_api_pricing)
 
 ## Quick Start
 
@@ -186,6 +188,48 @@ data/snapshots/<YYYY-MM-DD>/prices.json
 data/snapshots/<YYYY-MM-DD>/prices.csv
 ```
 
+### Price Change Events
+
+Canonical price change events are stored in:
+
+```text
+data/price-change-events/events.jsonl
+```
+
+A price change event is different from a normal history verification row. History rows record source verification state for a model and may change when `last_verified_at`, `official_source_url`, or notes change. Price change events record only verified pricing semantics: input price, cached input price, output price, unit, and currency changes between two trusted snapshots.
+
+Baseline snapshots are not price changes. New snapshots, reordered files, source URL edits, status changes, or repeated verification dates must not create price change events when the prices are unchanged.
+
+Date fields use separate meanings:
+
+- `effective_from`: provider-announced effective date only. It stays `null` when the provider did not publish one.
+- `detected_at`: the first snapshot date where the repository observed the change by comparing trusted snapshots.
+- `verified_at`: the date the new price was checked against an official provider source.
+- `date_basis`: one of `provider_announced`, `official_changelog`, `first_observed`, or `unknown`.
+
+Preview events without writing:
+
+```bash
+python scripts\generate_price_change_events.py --before data\snapshots\2026-07-09\prices.json --after data\snapshots\2026-07-27\prices.json --dry-run
+```
+
+Generate the canonical JSONL projection:
+
+```bash
+python scripts\generate_price_change_events.py --before data\snapshots\2026-07-09\prices.json --after data\snapshots\2026-07-27\prices.json
+```
+
+The generator matches models by `provider_id + model_id`, compares only pricing semantics, writes stable sorted output, and merges by `dedupe_key`. The first version emits `price_update`, `cached_price_added`, and `cached_price_removed`; it does not emit `pricing_added` or `pricing_removed` because a model first appearing in a snapshot may be coverage expansion rather than an official pricing launch. The dedupe key is based on provider, model, old prices, new prices, unit, currency, and change type. It excludes `verified_at`, `announcement_url`, and notes so later metadata backfills update the same event instead of creating a duplicate.
+
+Manual backfills should edit the existing event with the same `dedupe_key`. Add `effective_from` only when an official provider announcement, official changelog, or pricing page explicitly gives the effective date. Add `announcement_url` only for an official URL; do not invent one.
+
+Current canonical event count is 2:
+
+- Mistral AI `mistral-large`: `price_update`
+- xAI `grok-4.3`: `cached_price_added`
+
+The current data is not ready for a public Pricing History page. Suggested readiness gates are at least 5 real price changes, at least 3 providers covered, official source for every event, `detected_at` and `verified_at` for every event, explicit marking of unknown effective dates, and no inferred old prices.
+
 ## Methodology
 
 Prices are accepted only from official provider pricing pages, official documentation, official APIs, or official announcements. Third-party calculators, SEO pages, Reddit posts, and competitor aggregators are not used as final price sources.

diff --git a/data/price-change-events/events.jsonl b/data/price-change-events/events.jsonl
@@ -0,0 +1,2 @@
+{"announcement_url":null,"change_type":"price_update","currency":"USD","date_basis":"first_observed","dedupe_key":"sha256:2c926ae1b4b546f3eac7149e0ab781a0bdce06715d81eae8d595887bfdb39cc0","detected_at":"2026-07-27","effective_from":null,"event_id":"mistral-ai:mistral-large:price_update:2c926ae1b4b5","model_id":"mistral-large","new_prices":{"cached_input":0.05,"input":0.5,"output":1.5},"notes":"Effective date was not published by the provider in the source used for this event.","official_source_url":"https://mistral.ai/pricing/api/","old_prices":{"cached_input":null,"input":2,"output":6},"provider_id":"mistral-ai","schema_version":"1.0","source_snapshot_after":"data/snapshots/2026-07-27/prices.json","source_snapshot_before":"data/snapshots/2026-07-09/prices.json","unit":"1M tokens","verified_at":"2026-07-27"}
+{"announcement_url":null,"change_type":"cached_price_added","currency":"USD","date_basis":"first_observed","dedupe_key":"sha256:ba960d39b16970bae4345149e90cb43e6ff54be6829307024d213f7da31ce971","detected_at":"2026-07-27","effective_from":null,"event_id":"xai:grok-4.3:cached_price_added:ba960d39b169","model_id":"grok-4.3","new_prices":{"cached_input":0.2,"input":1.25,"output":2.5},"notes":"Effective date was not published by the provider in the source used for this event.","official_source_url":"https://docs.x.ai/developers/pricing","old_prices":{"cached_input":null,"input":1.25,"output":2.5},"provider_id":"xai","schema_version":"1.0","source_snapshot_after":"data/snapshots/2026-07-27/prices.json","source_snapshot_before":"data/snapshots/2026-07-09/prices.json","unit":"1M tokens","verified_at":"2026-07-27"}
diff --git a/schema/price-change-event.schema.json b/schema/price-change-event.schema.json
@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aicostbudget.com/schemas/ai-api-pricing/price-change-event.schema.json",
+  "title": "AI API Pricing Price Change Event",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "event_id",
+    "provider_id",
+    "model_id",
+    "change_type",
+    "old_prices",
+    "new_prices",
+    "unit",
+    "currency",
+    "effective_from",
+    "detected_at",
+    "verified_at",
+    "date_basis",
+    "official_source_url",
+    "announcement_url",
+    "source_snapshot_before",
+    "source_snapshot_after",
+    "dedupe_key",
+    "notes"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {"type": "string", "const": "1.0"},
+    "event_id": {"type": "string", "minLength": 1},
+    "provider_id": {"type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$"},
+    "model_id": {"type": "string", "minLength": 1},
+    "change_type": {
+      "type": "string",
+      "enum": [
+        "price_update",
+        "cached_price_added",
+        "cached_price_removed"
+      ]
+    },
+    "old_prices": {"$ref": "#/$defs/priceTriple"},
+    "new_prices": {"$ref": "#/$defs/priceTriple"},
+    "unit": {"type": "string", "enum": ["1M tokens"]},
+    "currency": {"type": "string", "const": "USD"},
+    "effective_from": {"type": ["string", "null"], "format": "date"},
+    "detected_at": {"type": "string", "format": "date"},
+    "verified_at": {"type": "string", "format": "date"},
+    "date_basis": {
+      "type": "string",
+      "enum": [
+        "provider_announced",
+        "official_changelog",
+        "first_observed",
+        "unknown"
+      ]
+    },
+    "official_source_url": {"type": "string", "format": "uri", "pattern": "^https://"},
+    "announcement_url": {"type": ["string", "null"], "format": "uri"},
+    "source_snapshot_before": {"type": "string", "minLength": 1},
+    "source_snapshot_after": {"type": "string", "minLength": 1},
+    "dedupe_key": {"type": "string", "minLength": 1},
+    "notes": {"type": "string"}
+  },
+  "$defs": {
+    "priceTriple": {
+      "type": "object",
+      "required": ["input", "cached_input", "output"],
+      "additionalProperties": false,
+      "properties": {
+        "input": {"type": ["number", "null"], "minimum": 0},
+        "cached_input": {"type": ["number", "null"], "minimum": 0},
+        "output": {"type": ["number", "null"], "minimum": 0}
+      }
+    }
+  }
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		{"announcement_url":null,"change_type":"price_update","currency":"USD","date_basis":"first_observed","dedupe_key":"sha256:2c926ae1b4b546f3eac7149e0ab781a0bdce06715d81eae8d595887bfdb39cc0","detected_at":"2026-07-27","effective_from":null,"event_id":"mistral-ai:mistral-large:price_update:2c926ae1b4b5","model_id":"mistral-large","new_prices":{"cached_input":0.05,"input":0.5,"output":1.5},"notes":"Effective date was not published by the provider in the source used for this event.","official_source_url":"https://mistral.ai/pricing/api/","old_prices":{"cached_input":null,"input":2,"output":6},"provider_id":"mistral-ai","schema_version":"1.0","source_snapshot_after":"data/snapshots/2026-07-27/prices.json","source_snapshot_before":"data/snapshots/2026-07-09/prices.json","unit":"1M tokens","verified_at":"2026-07-27"}
		{"announcement_url":null,"change_type":"cached_price_added","currency":"USD","date_basis":"first_observed","dedupe_key":"sha256:ba960d39b16970bae4345149e90cb43e6ff54be6829307024d213f7da31ce971","detected_at":"2026-07-27","effective_from":null,"event_id":"xai:grok-4.3:cached_price_added:ba960d39b169","model_id":"grok-4.3","new_prices":{"cached_input":0.2,"input":1.25,"output":2.5},"notes":"Effective date was not published by the provider in the source used for this event.","official_source_url":"https://docs.x.ai/developers/pricing","old_prices":{"cached_input":null,"input":1.25,"output":2.5},"provider_id":"xai","schema_version":"1.0","source_snapshot_after":"data/snapshots/2026-07-27/prices.json","source_snapshot_before":"data/snapshots/2026-07-09/prices.json","unit":"1M tokens","verified_at":"2026-07-27"}