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

# Analyzing with statistics

> Cited source domain and URL rankings, and fan-out query aggregation

These endpoints aggregate collected answers on the server and return rankings. Use them instead of downloading every answer and aggregating it yourself.

## Common rules

* Cited domain, URL, and fan-out statistics require **at least one** of `runIDs` or `promptIDs` to set the scope. You cannot aggregate an entire organization at once.
* Pass multiple values by **repeating the parameter** (`?runIDs=a&runIDs=b`; up to 5 `runIDs` and up to 10 `promptIDs`). Comma-separated values are not supported. If you send a comma-separated string, it is treated as a single value.
* Use `model` to narrow aggregation to answers from a specific model.
* Results are a top-N ranking. `limit` defaults to 50 and is capped at 200. There is no cursor pagination.
* The full rules are defined in [Statistics common rules](https://dev-docs.trychainshift.ai/en/api-reference/statistics/statistics-overview.md), which is the source of truth.

## Cited domain ranking

See which domains are cited most often in AI answers. This is the core data for answering "which sources should I target?"

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

Below is a real aggregation from running 140 used-car prompts across 8 models (top 2 shown).

```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 }
      ]
    }
  ]
}
```

What the per-model breakdown reveals: in this market, a third of all 800 citations point to Naver content, and YouTube is cited mainly by Perplexity and Google AI while ChatGPT almost never cites it (1 of 74). In other words, the content channel you need to build depends on which model you target.

* Set `groupBy=subdomain` to aggregate at the subdomain level (the default is domain level).
* Set `include=models` to include per-model citation counts for each domain.
* Use the `domains` parameter (repeatable, up to 50) to retrieve specific domains only. Matching follows `groupBy`.
* `totalDomains` is returned as `null` when the number of distinct domains exceeds the internal aggregation limit.

## Cited URL ranking

Go one level deeper than domains and see which pages are cited.

```bash theme={null}
curl -H "API-Key: YOUR_API_KEY" \
  "https://dev-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. 가격대별 인기 중고차 구매 꿀팁. 이번 … 눈여겨보신다면, 가성비 및 실용성 측면에서 후회 없는"
      ]
    }
  ]
}
```

Set `include=quotes` to include the sentences the AI actually quoted from each page. As in the example above, you can see which sentences from magazine-style content get quoted, which is a direct hint about what kind of writing AI models cite well. When the same document appears under several URL forms (such as a mobile subdomain), they are normalized automatically and counted as one.

* Set `groupBy=subdomain` to switch both the `domains` filter matching and each entry's `domain` field to the subdomain axis. You can paste values from the domain ranking (`groupBy=subdomain`) directly to drill down.
* Set `include=models` to include per-model citation counts for each URL (same pattern as domain statistics).
* If you need the **list of answers that cited** a specific URL, pass the `url` value from the response unchanged to `GET /answers?sourceURL=…`. For the domain level, use `sourceDomain`.

## Fan-out query aggregation

A ranking of the fan-out queries AI models actually issued to build their answers. It shows which search terms AI uses to find information, and therefore which search terms your content needs to rank for in order to be cited.

```bash theme={null}
curl -H "API-Key: YOUR_API_KEY" \
  "https://dev-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` is the total number of fan-outs across the whole query scope. You can compute each query's share as `fanoutCount ÷ totalFanouts`.
* The distinct `models` and `regions` lists per query are included only when you set `include=models` and `include=regions`.

User prompts are conversational, like "중고 전기차 살 때 주의할 점 알려줘" (a Korean prompt asking what to watch out for when buying a used EV), but the fan-out queries AI actually issues are noun-stacked, like "중고 전기차 구매 주의사항 배터리 성능 점검" (used EV purchase precautions battery performance check). Creating content that ranks for search terms in this form is the starting point of AEO.

> [!WARNING]
>
> Fan-outs are collected only from ChatGPT, Perplexity, and Claude answers. If
> you ran only other models, the result is empty. See [Supported models](https://dev-docs.trychainshift.ai/en/models.md).

## Comparing across runs

Run the same prompt set at different points in time and compare the two rankings to see how citations change (your visibility trend). There is no per-run breakdown parameter; the intended usage is to **call the endpoint once per run and compare on the client**. Watch out for one trap: the top N differs between runs, so a domain that ranks high in run A but falls outside the ranking in run B leaves a hole in your comparison table. Solve it with the following two-step pattern.

1. **Collect the comparison keys**: call the domain statistics once for each run and build the union of the domain keys you want to compare.
2. **Query again with explicit keys**: pass those keys in the `domains` filter (up to 50) and query each run again. Domains outside the top N also return metrics when specified, so every cell in the comparison table is filled.

```bash theme={null}
# Step 2: query each run with the same domain set
curl -H "API-Key: YOUR_API_KEY" \
  "https://dev-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://dev-platform-api.trychainshift.ai/api/v1beta/platform/sources/statistics/domains?runIDs=RUN_B&domains=naver.com&domains=youtube.com&domains=mybrand.com"
```

For ratio comparisons, use each response's `totalCitations` as the denominator. The number of successful answers differs between runs, so comparing raw counts is misleading.

## Frequently asked questions

**The statistics result is empty.**
Either the run is still in progress (check with `GET /runs/:runID`), or the specified `runIDs`/`promptIDs` have no successful answers. Fan-out statistics are also empty if you ran only models that do not support fan-out.

**I want to see trends over time for my whole organization.**
Statistics are currently snapshots per run or per prompt. Submit runs on a regular schedule and store each run's statistics using the [Comparing across runs](#comparing-across-runs) pattern above to compare them.


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