Skip to main content
The statistics APIs aggregate collected answers on the server and return a top-N ranking. There are three endpoints: cited domains, cited URLs, and fan-out queries. They behave differently from the list APIs, so read the common rules below first. This page is the canonical source of the statistics API rules, and any statistics endpoints added later follow them too.

Scope rules

Filters that accept multiple values use plural names (runIDs, promptIDs, domains). Singular-name parameters (such as promptID in the list APIs) always accept exactly one value.

Ranking and totals

  • The result is a ranking containing only the top limit items (default 50, max 200). There is no cursor pagination.
  • Each item’s count field names the unit it counts: citation statistics use citationCount (1 citation = 1), fan-out statistics use fanoutCount (1 fan-out occurrence = 1).
  • The response also includes totals for the whole queried scope: totalCitations (domain and URL statistics) and totalFanouts (fan-out statistics). You can compute ratios (share) even when the ranking is truncated.
  • The number of distinct aggregation units is provided only when the cardinality is manageable: totalDomains is null when the number of distinct domains exceeds an internal limit, and a distinct URL count is not provided.

groupBy: aggregation axis

  • Domain and URL statistics choose the axis with groupBy: domain (default, merged at eTLD+1, so blog.naver.com and cafe.naver.com → naver.com) or subdomain (keeps subdomains separate; www. is always stripped).
  • The matching rule of the domains filter and the notation of each item’s domain field follow the same axis. You can drill down by passing a value from the domain ranking straight into the domains filter of the URL statistics.

include opt-ins

Supplementary or heavy fields are excluded by default. Request them with include= (repeatable).

From statistics to the original answers

Values you see in citation statistics can go straight into the answer list filters: GET /answers?sourceDomain=… or GET /answers?sourceURL=…. The drill-down path is domain ranking → URL ranking → answers that cite that source. See the Analyzing with statistics guide for real examples, interpretation, and how to compare across runs.