diff --git a/examples/README.md b/examples/README.md
index f661f98e..bcc53473 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -108,6 +108,9 @@ good:
 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.
+While the local UI is running, scripts, dashboards, or automation checks can
+also call `GET /api/compare/<failed_run_id>/<success_run_id>` for the same
+first-divergence JSON payload.
 
 ## Example Matrix
 
diff --git a/tests/test_metadata.py b/tests/test_metadata.py
index 1fa1234b..e761b974 100644
--- a/tests/test_metadata.py
+++ b/tests/test_metadata.py
@@ -3208,6 +3208,9 @@ def test_examples_readme_includes_command_cheat_sheet():
     assert "error: upload preview did not appear" in examples_readme
     assert "`browsertrace compare <failed_run_id> <success_run_id> --json`" in examples_readme
     assert "structured comparison output" in " ".join(examples_readme.split())
+    assert "`GET /api/compare/<failed_run_id>/<success_run_id>`" in examples_readme
+    assert "scripts, dashboards, or automation checks" in examples_readme
+    assert "same first-divergence JSON payload" in " ".join(examples_readme.split())
     assert 'pip install "browsertrace[ui]"' in examples_readme
     assert "hosted sharing" not in examples_readme