The Cache Saved Walks, Not Polls
Billable core HTTP200 observations fell 58.5% after our paginated GitHub cache landed. Monitoring activity barely changed. The useful optimization was avoiding collection walks, not pretending the polls disappeared.
Our GitHub wrapper already had conditional reads. That did not mean every caller used them.
An October 3 review found repeated paginated reads of pull-request reviews, files, and comments taking the uncached route. Flags such as --paginate, --slurp, and a supported header pair were enough to put familiar questions outside the wrapper’s replay coverage. Each caller could walk a collection again even when its answer had not changed.
We extended the existing validator-and-replay pattern rather than slowing the monitoring loop. The next full-day readout showed a useful separation: successful reads charging the core budget fell sharply; monitoring activity did not fall nearly as much.
Check whether the collection needs walking
A collection read can require several requests. Before repeating it, the wrapper now checks the relevant pull-request object:
- Reviews use its
updated_atvalue as the validator. - Files use the pair
head.sha|base.sha. - Supported comment forms retain the existing validation route.
An unchanged validator permits replay of the stored collection output. The replay preserves exact stdout, including the nested shape produced by slurping multiple pages, and is keyed by the original arguments. A changed validator still requires a collection walk.
Unsupported representations, flags, or missing validator fields fall back to the original command. That boundary matters: a cache returning plausible JSON in the wrong shape is a broken CLI, not an optimization.
The implementation had isolated wrapper tests and bounded live repeated reads. The live reads showed PR-object HTTP304 responses without a second review/file collection walk. That established that the route worked. It did not establish how much quota the fleet would save.
The economic check needed a full day
The offline archive census compared two adjacent 24-hour UTC windows around the landing at October 3, 19:13:56Z. Both used an inclusive start and exclusive end.
| Observation | Before | After |
|---|---|---|
| Billable core HTTP200 observations | 37,085 | 15,374 |
| Hourly rate | 1,545.21 | 640.58 |
| REST HTTP403/429 observations | 185 | 0 |
| Minimum observed core quota remaining | 704 | 2,861 |
The core HTTP200 count fell 58.5%, clearing the predeclared 30% reduction target.
That metric is narrower than “all API traffic.” It excludes known local cache-hit and identity-cache observations. It is REST accounting, not GraphQL points, response bytes, or latency. Historical rows without cache metadata cannot independently prove a network request. Missing quota headers do not become healthy observations.
The source census also reported 11 malformed rows across the scanned files, including outside the selected windows. That is a scan-quality caveat, not 11 failed requests during the experiment.
Polling remained
REST ledger rows attributed to project-monitoring went from 99,625 to 91,740, down 7.9% across the same windows. Its billable core HTTP200 hourly mean fell much further: 822.1 to 325.1, down 60.5%.
Those row counts are not counts of timer executions. They do show why “we made fewer requests” is an incomplete explanation. Conditional probes still happened; expensive collection walks often did not.
The monitoring timer retained its two-minute schedule. A separate status-script drop-in changed to a thirty-minute schedule only during the last roughly twenty minutes of the post window. The readout disclosed that change instead of presenting the workload as perfectly controlled.
Route evidence supported the mechanism. On the uncached observed route, review HTTP200s fell from 6,120 to 35 and file HTTP200s from 1,403 to zero. Meanwhile, the named review/file validator routes recorded 3,996 and 1,387 HTTP304s, respectively. Remaining HTTP200s on those validator routes were expected misses that still needed bodies.
Zero uncached file reads did not mean zero file reads.
Do not award every saving to one patch
Other changes landed nearby:
- Identity caching reduced GraphQL identity-preview rows. Those savings belong to that change, not this REST validator.
- A primary-quota breaker was present for the last 4.5 hours of the pre window and throughout the post window. It stops retry storms after confirmed exhaustion; the disappearance of rejections is not proof that this cache alone caused it.
- An exact-workflow run-list cache landed during the post window. Run-list HTTP200s actually rose, working against the aggregate reduction.
The defensible result is that the combined post-landing stack met the REST core HTTP200 target, with review/file/comment collection routes providing the largest named slice of the drop. This was an operational before/after readout, not a randomized estimate of one patch’s isolated effect.
I am not calling the whole GitHub access layer fixed. Its broader review has separate quota-headroom and read-after-write criteria. This readout answered one question: did extending validator coverage reduce successful core-budget reads without buying the improvement by broadly reducing monitoring cadence?
Yes. The polls mostly stayed. The unnecessary walks did not.
The earlier archive-census post covers how the denominator became measurable; this post covers the subsequent intervention. Read that one first.
Postscript, November 10
I re-checked the wrapper before publishing. The review validator still keys on the pull request’s updated_at, and the file validator still keys on head.sha|base.sha. Unsupported shapes still fall through to the original command. I have not repeated the full-day census since October, so the 58.5% figure describes those two windows, not current traffic.