# Index 汇总与趋势

`GET https://api.dataforgeo.dev/v1/geo/index/summary` · Pro / Scale / Enterprise

把账户里已经跑过的 /v1/geo/index 结果按时间窗口汇总成 KPI 和趋势，不产生新的 AI 调用，不扣费。Pro 可看总体与趋势；按维度拆分（group_by）仅 Scale 与 Enterprise。

### 参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `brand` | string | 是 | 品牌名，与 index 请求一致 |
| `tag` | string | 否 | 只汇总该标签下的请求 |
| `from / to` | string | 否 | 时间窗口，ISO 8601；默认最近 30 天 |
| `interval` | string | 否 | 趋势粒度：day、week、month，默认 week |
| `engines` | string | 否 | 逗号分隔，只看这些引擎 |
| `kpis` | string | 否 | 逗号分隔，只返回这些 KPI；默认返回本档位全部 |
| `group_by` | string | 否 | engine、intent、persona、prompt，一次一个；仅 Scale (Scale) |

### 请求示例

```bash
curl "https://api.dataforgeo.dev/v1/geo/index/summary?brand=晓宅&tag=osaka-family-q4&interval=week&group_by=engine" \
  -H "x-api-key: YOUR_API_KEY"
```

### 响应示例

```json
{
  "brand": "晓宅",
  "window": {
    "from": "2026-10-03T00:00:00Z",
    "to": "2026-11-02T00:00:00Z"
  },
  "answers_counted": 498,
  "kpis": {
    "findability": {
      "value": 42.1
    },
    "visibility": {
      "value": 0.262,
      "numerator": 130,
      "denominator": 498
    }
  },
  "series": [
    {
      "period": "2026-10-05",
      "visibility": 0.255,
      "share_of_voice": 0.018
    },
    {
      "period": "2026-10-12",
      "visibility": 0.263,
      "share_of_voice": 0.026
    }
  ],
  "groups": [
    {
      "key": "chatgpt",
      "answers_counted": 166,
      "kpis": {
        "visibility": {
          "value": 0.301
        }
      }
    },
    {
      "key": "gemini",
      "answers_counted": 166,
      "kpis": {
        "visibility": {
          "value": 0.241
        }
      }
    }
  ]
}
```

- 部分 KPI 只在汇总里提供，单次 index 请求不返回，例如 knowledge_half_life、category_capture_gap。
- 汇总只用本账户的 index 结果；跨账户共享的只是答案缓存，不共享 KPI 和标签。