> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychainshift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Common statistics rules

> The canonical scope, ranking, opt-in, and naming rules that apply to every statistics API

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

| Rule | Details |
| - | - |
| Scope is required | **At least one** of `runIDs` or `promptIDs`. Organization-wide aggregation is not available |
| Multiple values | **Repeat the parameter** to pass several values (`?runIDs=a&runIDs=b`; up to 5 `runIDs`, up to 10 `promptIDs`). Values within one parameter are a union; passing both parameters gives the intersection |
| No comma separation | A comma-separated value like `?runIDs=a,b` is treated as **a single value**. For IDs this returns 400 `COMMON_BINDING`; for domains it returns an empty result |
| `model` filter | Aggregate only answers from one model (optional, single value) |

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).

| Value | Endpoint | What it adds |
| - | - | - |
| `models` | Cited domain ranking | Per-domain counts broken down by model |
| `models` | Cited URL ranking | Per-URL counts broken down by model |
| `models` | Fan-out query aggregation | Distinct models per query |
| `regions` | Fan-out query aggregation | Distinct regions per query |
| `quotes` | Cited URL ranking | Sentences the AI actually quoted |
| `urlVariants` | Cited URL ranking | Original URLs merged by normalization |

## 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](https://docs.trychainshift.ai/en/guides/analytics.md) guide for real examples, interpretation, and how to compare across runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.