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

# 통계로 분석하기

> 인용 출처 도메인·URL 랭킹, fan-out 쿼리 집계

수집된 답변을 서버에서 집계해 랭킹으로 반환하는 엔드포인트들입니다. 답변을 전부 내려받아 직접 집계하는 대신 이 API를 사용하세요.

## 공통 규칙

* 인용 도메인·URL·fan-out 통계는 `runIDs` 또는 `promptIDs` 중 **최소 하나**로 범위를 지정해야 합니다. 조직 전체를 한 번에 집계할 수는 없습니다.
* 복수 값은 같은 파라미터를 **반복 전달**합니다(`?runIDs=a&runIDs=b`, `runIDs` 최대 5개·`promptIDs` 최대 10개). 콤마 구분은 지원하지 않습니다 — 콤마로 보내면 통째로 한 값으로 취급됩니다.
* `model`로 특정 모델의 답변만 집계하도록 좁힐 수 있습니다.
* 결과는 상위 N개 랭킹입니다. `limit`은 기본 50, 최대 200이며 페이지네이션(cursor)은 없습니다.
* 전체 규칙은 [통계 공통 규칙](/api-reference/statistics/statistics-overview)이 정본입니다.

## 인용 도메인 랭킹

어떤 도메인이 AI 답변에 가장 많이 인용됐는지 봅니다. "어떤 소스를 공략해야 하나"에 답하는 핵심 데이터입니다.

```bash theme={null}
curl -H "API-Key: YOUR_API_KEY" \
  "https://platform-api.trychainshift.ai/api/v1beta/platform/sources/statistics/domains?runIDs=0PCCDohFaNRcUWjLGoBGfw&include=models"
```

아래는 중고차 관련 프롬프트 140개를 8개 모델에 실행한 결과의 실제 집계입니다(상위 2개만 표시).

```json theme={null}
{
  "totalCitations": 800,
  "totalDomains": 144,
  "domains": [
    {
      "domain": "naver.com",
      "citationCount": 264,
      "models": [
        { "model": "NAVER_AI_TAB", "citationCount": 85 },
        { "model": "PERPLEXITY", "citationCount": 61 },
        { "model": "NAVER_AI_BRIEFING", "citationCount": 56 },
        { "model": "GOOGLE_OVERVIEW", "citationCount": 39 },
        { "model": "GOOGLE_AI", "citationCount": 23 }
      ]
    },
    {
      "domain": "youtube.com",
      "citationCount": 74,
      "models": [
        { "model": "PERPLEXITY", "citationCount": 38 },
        { "model": "GOOGLE_AI", "citationCount": 30 },
        { "model": "GEMINI", "citationCount": 4 },
        { "model": "CHATGPT", "citationCount": 1 },
        { "model": "GOOGLE_OVERVIEW", "citationCount": 1 }
      ]
    }
  ]
}
```

모델 분해가 있어야 보이는 것: 이 시장에서는 전체 인용 800건 중 1/3이 네이버 콘텐츠이고, 유튜브는 Perplexity·Google AI가 주로 인용하지만 ChatGPT는 거의 인용하지 않습니다(74건 중 1건). 어떤 모델을 공략하느냐에 따라 만들어야 할 콘텐츠 채널이 달라진다는 뜻입니다.

* `groupBy=subdomain`을 지정하면 서브도메인 단위로 집계합니다(기본은 도메인 단위).
* `include=models`를 지정하면 도메인별 모델 분해 카운트가 포함됩니다.
* `domains` 파라미터(반복 가능, 최대 50개)로 특정 도메인만 조회할 수 있습니다. 매칭 기준은 `groupBy`를 따릅니다.
* `totalDomains`는 도메인 종류가 내부 집계 상한을 넘으면 `null`로 반환됩니다.

## 인용 URL 랭킹

도메인보다 한 단계 깊게, 어떤 페이지가 인용됐는지 봅니다.

```bash theme={null}
curl -H "API-Key: YOUR_API_KEY" \
  "https://platform-api.trychainshift.ai/api/v1beta/platform/sources/statistics/urls?runIDs=0PCCDohFaNRcUWjLGoBGfw&domains=kbchachacha.com&include=quotes"
```

```json theme={null}
{
  "totalCitations": 800,
  "urls": [
    {
      "url": "https://kbchachacha.com/public/web/magazine/detail.kbc?magazineSeq=36430",
      "domain": "kbchachacha.com",
      "citationCount": 5,
      "quotes": [
        "중고차는 비교적 저렴한 가격에 취향과 라이프스타일에 맞는 … 선택을 하는 데 큰 도움이 되리라 생각합니다",
        "4. 가격대별 인기 중고차 구매 꿀팁. 이번 … 눈여겨보신다면, 가성비 및 실용성 측면에서 후회 없는"
      ]
    }
  ]
}
```

`include=quotes`를 지정하면 AI가 해당 페이지에서 실제로 인용한 문장이 포함됩니다. 위 예시처럼 매거진형 콘텐츠의 어떤 문장이 인용되는지 보이므로, 어떤 형식의 문장이 AI에 잘 인용되는지의 직접적인 힌트가 됩니다. 같은 문서의 URL 표기가 여러 개인 경우(모바일 서브도메인 등)는 자동으로 정규화되어 하나로 집계됩니다.

* `groupBy=subdomain`을 지정하면 `domains` 필터의 매칭 기준과 항목 `domain` 필드가 서브도메인 축으로 바뀝니다 — 도메인 랭킹(`groupBy=subdomain`)에서 본 값을 그대로 넣어 드릴다운할 수 있습니다.
* `include=models`를 지정하면 URL별 모델 분해 카운트가 포함됩니다(도메인 통계와 동일 패턴).
* 특정 URL을 **인용한 답변 목록**이 필요하면 응답의 `url` 값을 그대로 `GET /answers?sourceURL=…`에 넣으세요. 도메인 단위는 `sourceDomain`입니다.

## fan-out 쿼리 집계

AI가 답변을 만들기 위해 실제로 던진 팬아웃의 랭킹입니다. AI가 어떤 검색어로 정보를 찾는지 — 즉 어떤 검색어에서 인용될 콘텐츠를 만들어야 하는지 보여줍니다.

```bash theme={null}
curl -H "API-Key: YOUR_API_KEY" \
  "https://platform-api.trychainshift.ai/api/v1beta/platform/fanouts/statistics?runIDs=0PCCDohFaNRcUWjLGoBGfw&include=models&include=regions"
```

```json theme={null}
{
  "totalFanouts": 128,
  "fanouts": [
    {
      "query": "중고 전기차 구매 주의사항 배터리 성능 점검",
      "fanoutCount": 1,
      "models": ["CHATGPT"],
      "regions": ["KR"],
      "latestCreatedAt": "2026-07-28T06:29:12Z"
    },
    {
      "query": "한국 중고차 평균 주행거리 연식별 구매 기준",
      "fanoutCount": 1,
      "models": ["CHATGPT"],
      "regions": ["KR"],
      "latestCreatedAt": "2026-07-28T06:29:00Z"
    }
  ]
}
```

* `totalFanouts`는 조회 범위 전체의 총 fan-out 발생 수입니다 — `fanoutCount ÷ totalFanouts`로 쿼리별 비중을 계산할 수 있습니다.
* 쿼리별 `models`·`regions` distinct 목록은 `include=models`·`include=regions`를 지정할 때만 포함됩니다.

사용자 프롬프트는 "중고 전기차 살 때 주의할 점 알려줘"처럼 구어체지만, AI가 실제로 던진 팬아웃은 "중고 전기차 구매 주의사항 배터리 성능 점검"처럼 명사 나열형입니다. 이 형태의 검색어에서 검색되는 콘텐츠를 만드는 것이 AEO의 출발점입니다.

<Warning>
  fan-out은 ChatGPT · Perplexity · Claude 답변에서만 수집됩니다. 다른 모델만
  실행한 경우에는 결과가 비어 있습니다. [지원 모델](/models) 참고.
</Warning>

## 실행(run) 간 비교하기

같은 프롬프트 세트를 시점을 달리해 실행하고 두 랭킹을 비교하면 인용 변화(가시성 추이)를 볼 수 있습니다. run별 분해 파라미터는 없으며, **run마다 따로 호출해 클라이언트에서 비교**하는 것이 의도된 사용법입니다. 이때 함정 하나를 주의하세요 — run별 상위 N이 서로 달라서, run A에서 상위인 도메인이 run B의 랭킹 밖이면 비교표에 구멍이 생깁니다. 다음 2단계 패턴으로 해결합니다.

1. **비교 대상 키 수집**: 각 run에 도메인 통계를 한 번씩 호출해, 비교하고 싶은 도메인 키의 합집합을 만듭니다.
2. **키 지정 재조회**: 그 키들을 `domains` 필터(최대 50개)로 지정해 각 run을 다시 조회합니다. 상위 N 밖 도메인도 지정하면 지표가 반환되므로 비교표의 모든 칸이 채워집니다.

```bash theme={null}
# 2단계: run 별로 같은 도메인 셋을 지정해 조회
curl -H "API-Key: YOUR_API_KEY" \
  "https://platform-api.trychainshift.ai/api/v1beta/platform/sources/statistics/domains?runIDs=RUN_A&domains=naver.com&domains=youtube.com&domains=mybrand.com"
curl -H "API-Key: YOUR_API_KEY" \
  "https://platform-api.trychainshift.ai/api/v1beta/platform/sources/statistics/domains?runIDs=RUN_B&domains=naver.com&domains=youtube.com&domains=mybrand.com"
```

비율 비교에는 각 응답의 `totalCitations`를 분모로 쓰세요 — run마다 성공 답변 수가 달라 건수 비교는 왜곡됩니다.

## 자주 묻는 질문

**통계 결과가 비어 있어요.**
실행이 아직 진행 중이거나(`GET /runs/:runID`로 확인), 지정한 `runIDs`/`promptIDs`에 성공한 답변이 없는 경우입니다. fan-out 통계는 fan-out을 지원하지 않는 모델만 실행했을 때도 비어 있습니다.

**조직 전체 기간별 추이를 보고 싶어요.**
현재 통계는 실행·프롬프트 단위 스냅샷입니다. 실행을 정기 제출하고 위의 [실행 간 비교하기](#실행run-간-비교하기) 패턴으로 실행별 통계를 저장해 비교하세요.