Aggregated answer-visibility stats endpoint (per-query mention/citation rate with sample size, optional per-provider)

[arberx]

Context

Answer-visibility runs emit one snapshot per (query × provider) carrying the tri-state answerMentioned (true / false / null=unchecked) and citationState. Today the only way to read these is per run, via GET /api/v1/runs/:id (RunDetail.snapshots).

Problem

To compute a per-query mention/citation rate with a sample size across multiple runs (e.g. a visibility trend, or a confidence-aware estimate), a consumer must fetch every run and aggregate client-side. That is O(runs) requests, does not scale, and makes per-provider and confidence-interval analysis awkward. A single run is n=1 per provider, which is far too small to estimate a rate; the value is in aggregating across runs over time.

Proposal

Add an aggregate endpoint, roughly:

GET /api/v1/projects/:name/visibility-stats
    ?since=<iso>&until=<iso>   (or ?lastRuns=N)
    &groupBy=provider          (optional)

returning, per query:

• checked (n: snapshots where answerMentioned != null)
• mentioned (count where answerMentioned === true)
• cited (count where citationState === 'cited')
• optional per-provider breakdown of the same counts
• firstObserved / lastObserved

Why

Lets a consumer compute a proportion + confidence interval (e.g. Wilson) and provider-specific rates directly, enabling confidence-aware visibility reporting and drift detection without N+1 fetches.

Constraints

• Preserve the tri-state rule: answerMentioned: null (unchecked) must be excluded from checked, never counted as not-mentioned. Keep mentioned (answer text) and cited (grounding) independent.
• Backward compatible; per-provider grouping optional.

Acceptance

• Documented response shape + a fixture.
• Counts respect the tri-state and the mention-vs-citation separation.
• groupBy=provider returns per-provider counts that sum to the pooled counts.