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

# 통계 공통 규칙

> 통계 API 전체에 적용되는 스코프·랭킹·옵트인·명명 규칙의 정본

통계 API는 수집된 답변을 서버에서 집계해 **상위 N개 랭킹**으로 반환합니다. 인용 도메인·인용 URL·fan-out 쿼리 세 엔드포인트가 있으며, 목록 API와 동작 방식이 다르므로 아래 공통 규칙을 먼저 확인하세요. 이 페이지가 통계 API 규칙의 정본이며, 이후 추가되는 통계 엔드포인트도 이 규칙을 따릅니다.

## 스코프 규칙

| 규칙         | 내용                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| 범위 지정 필수   | `runIDs` 또는 `promptIDs` 중 **최소 하나**. 조직 전체 집계는 불가                                                                        |
| 복수 지정      | 같은 파라미터를 **반복 전달**해 여러 개 지정 (`?runIDs=a&runIDs=b`, `runIDs` 최대 5개·`promptIDs` 최대 10개). 같은 파라미터 안은 합집합, 두 파라미터를 함께 주면 교집합 |
| 콤마 미지원     | `?runIDs=a,b` 처럼 콤마로 구분하면 **통째로 한 값**으로 취급됩니다 — ID면 400 `COMMON_BINDING`, 도메인이면 빈 결과                                     |
| `model` 필터 | 특정 모델의 답변만 집계 (선택, 단일 값)                                                                                                 |

복수 값을 받는 필터는 복수형 이름(`runIDs`·`promptIDs`·`domains`)을 씁니다. 단수 이름 파라미터(목록 API의 `promptID` 등)는 항상 값 하나만 받습니다.

## 랭킹·총계 규칙

* 결과는 상위 `limit`개만 담는 랭킹입니다(기본 50, 최대 200). **cursor 페이지네이션은 없습니다.**
* 항목의 카운트 필드는 세는 단위를 이름에 담습니다: 인용 통계는 `citationCount`(인용 1건 = 1), fan-out 통계는 `fanoutCount`(fan-out 발생 1회 = 1).
* 조회 범위 전체의 총계를 함께 반환합니다: `totalCitations`(도메인·URL 통계), `totalFanouts`(fan-out 통계). 랭킹이 잘려도 비율(점유율)을 계산할 수 있습니다.
* 고유 집계 단위 수는 카디널리티가 감당될 때만 제공합니다 — `totalDomains`는 도메인 종류가 내부 상한을 넘으면 `null`, 고유 URL 수는 제공하지 않습니다.

## `groupBy` — 집계 축

* 도메인·URL 통계는 `groupBy`로 축을 정합니다: `domain`(기본, eTLD+1 합산 — `blog.naver.com`·`cafe.naver.com` → `naver.com`) 또는 `subdomain`(서브도메인 구분, `www.`는 항상 제거).
* `domains` 필터의 매칭 기준과 항목 `domain` 필드 표기도 같은 축을 따릅니다 — **도메인 랭킹에서 본 값을 그대로 URL 통계의 `domains`에 넣어 드릴다운**할 수 있습니다.

## `include` 옵트인

부가/무거운 필드는 기본 제외이며 `include=`로 요청합니다(반복 지정 가능).

| 값             | 엔드포인트         | 추가되는 것             |
| ------------- | ------------- | ------------------ |
| `models`      | 인용 도메인 통계     | 도메인별 모델 분해 카운트     |
| `models`      | 인용 URL 통계     | URL별 모델 분해 카운트     |
| `models`      | fan-out 쿼리 통계 | 쿼리별 모델 distinct 목록 |
| `regions`     | fan-out 쿼리 통계 | 쿼리별 지역 distinct 목록 |
| `quotes`      | 인용 URL 통계     | AI가 실제 인용한 문장      |
| `urlVariants` | 인용 URL 통계     | 정규화로 합쳐진 원본 URL 목록 |

## 통계에서 원본 답변으로

인용 통계에서 본 값은 답변 목록 필터에 그대로 넣을 수 있습니다: `GET /answers?sourceDomain=…` 또는 `GET /answers?sourceURL=…`. 드릴다운 경로는 **도메인 랭킹 → URL 랭킹 → 그 출처를 인용한 답변** 순입니다.

실측 예시와 해석, run 간 비교 방법은 [통계로 분석하기](/guides/analytics) 가이드를 참고하세요.