diff --git a/examples/README.md b/examples/README.md
index f661f98e..d90f3d17 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -109,6 +109,14 @@ Use `browsertrace compare <failed_run_id> <success_run_id> --json` when a
 script, CI check, or AI/coding-agent troubleshooting flow needs structured
 comparison output.
 
+The local compare API (`GET /api/compare/<failed_run_id>/<success_run_id>`) is
+useful for scripts, dashboards, or automation checks that need the same
+first-divergence JSON payload while the local UI is running:
+
+```bash
+curl http://127.0.0.1:3000/api/compare/<failed_run_id>/<success_run_id>
+```
+
 ## Example Matrix
 
 | Example | Use when | Extra services | Command |
diff --git a/tests/test_metadata.py b/tests/test_metadata.py
index 1fa1234b..e96d26a2 100644
--- a/tests/test_metadata.py
+++ b/tests/test_metadata.py
@@ -98,6 +98,15 @@ def test_readme_intro_is_browser_use_first_for_pypi_description():
     assert "AI browser agents" not in intro
 
 
+def test_examples_guide_documents_local_compare_api():
+    project_root = Path(__file__).resolve().parents[1]
+    examples = (project_root / "examples" / "README.md").read_text()
+
+    assert "local compare API" in examples
+    assert "scripts, dashboards, or automation checks" in examples
+    assert "GET /api/compare/<failed_run_id>/<success_run_id>" in examples
+
+
 def test_social_preview_source_uses_browser_use_first_positioning():
     project_root = Path(__file__).resolve().parents[1]
     svg = (project_root / "docs" / "social-preview.svg").read_text()