# DataForGEO API
> DataForGEO 把一个 prompt 拿到多个 AI 搜索产品上去问，返回答案，并按品牌计算 GEO 指标（提及、引用、推荐位次等），按 credit 计费。
- Base URL: https://api.dataforgeo.dev
- Auth: `x-api-key` header (https://dashboard.dataforgeo.dev/keys)
- OpenAPI: https://docs.dataforgeo.dev/openapi.json
- 网页版: https://docs.dataforgeo.dev/

## 快速开始

所有接口用一个请求头认证：x-api-key。请求和响应都是 JSON，时间一律用 ISO 8601（UTC）。

| 项 | 说明 |
| --- | --- |
| Base URL | `https://api.dataforgeo.dev` |
| 认证 | `x-api-key` — 在控制台创建 API key；Pro 可建 5 个，Scale 和 Enterprise 不限 |
| 免费额度 | `100 credits` — 注册即送，可跑 100 次标准引擎调用 |

### 第一个请求

```bash
curl https://api.dataforgeo.dev/v1/geo/answer \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "东京有哪些适合家庭入住的民宿？",
    "engines": [
      "chatgpt"
    ],
    "brand": "晓宅",
    "location": "JP",
    "language": "zh-CN"
  }'
```

### 响应示例

```json
{
  "request_id": "req_8f2c1a",
  "prompt": "东京有哪些适合家庭入住的民宿？",
  "credits_used": 1,
  "answers": [
    {
      "engine": "chatgpt",
      "sample": 1,
      "status": "ok",
      "cached": false,
      "generated_at": "2026-11-02T00:31:12Z",
      "text": "……",
      "brand": {
        "mentioned": true,
        "mention_count": 2,
        "first_position": 3,
        "sentiment": "positive"
      },
      "entities": [
        {
          "name": "晓宅",
          "type": "brand",
          "position": 3,
          "is_competitor": false
        },
        {
          "name": "Example Stay",
          "type": "brand",
          "position": 1,
          "is_competitor": true
        }
      ],
      "citations": [
        {
          "url": "https://example.com/guide",
          "domain": "example.com",
          "position": 1,
          "is_brand_domain": false
        }
      ]
    }
  ]
}
```


## MCP、Skills 与 SDK

除了直接发 HTTP 请求，还有三种官方开源的接入方式：给 AI 助手用的 MCP 服务、给 agent 用的 Agent Skills、给自己代码用的 TypeScript / Python SDK。三者都只需要一个环境变量 DATAFORGEO_API_KEY，扣费规则和直接调用 API 完全相同。

| 方式 | 适合 | 安装 |
| --- | --- | --- |
| MCP 服务 | 让 Claude、Cursor 等 AI 助手直接拿到查询工具 | `npx -y @dataforgeo/mcp` |
| Agent Skills | 让 agent 按工作流完成体检、竞品对比、引用分析和周报 | `/plugin install dataforgeo@dataforgeo` |
| SDK | 在自己的 TypeScript / Python 代码里集成 | `npm install @dataforgeo/client` |

### MCP 服务

给 Claude Code、Claude Desktop、Cursor、Windsurf 等支持 MCP 的 AI 助手加上 6 个工具。stdio 传输，npx 直接运行，需要 Node.js 20 或以上。每个工具的描述里都写明了扣费规则，助手调用前就知道要花多少 credits。

```bash
claude mcp add dataforgeo -e DATAFORGEO_API_KEY=$DATAFORGEO_API_KEY -- npx -y @dataforgeo/mcp
```

```json
{
  "mcpServers": {
    "dataforgeo": {
      "command": "npx",
      "args": [
        "-y",
        "@dataforgeo/mcp"
      ],
      "env": {
        "DATAFORGEO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

| tool | API | 说明 | 扣费 |
| --- | --- | --- | --- |
| `geo_answer` | POST /v1/geo/answer | 一个 prompt 在多个引擎上的答案，标出品牌提及、引用和竞品 | 同 API |
| `geo_index` | POST /v1/geo/index | 同上，并计算 GEO Index KPI（Pro 及以上） | 同 API |
| `geo_index_summary` | GET /v1/geo/index/summary | 已跑结果的 KPI、趋势和维度拆分 | 0 |
| `get_job` | GET /v1/jobs/{job_id} | 查询异步任务，可用 wait_seconds 等待完成 | 0 |
| `get_account` | GET /v1/account | 档位、余额、本月用量 | 0 |
| `estimate_credits` | 本地计算 | 估算一次或一批调用最多预占多少 credits，不发请求 | 0 |

| 环境变量 | 必填 | 说明 |
| --- | --- | --- |
| `DATAFORGEO_API_KEY` | 是 | API key，作为请求头 x-api-key 发送 |
| `DATAFORGEO_BASE_URL` | 否 | 覆盖 API 地址 |
| `DATAFORGEO_MAX_CREDITS_PER_CALL` | 否 | 单次 geo_answer / geo_index 最多预占的 credits，超过则本地拒绝、不发请求。推荐给自动化 agent 设置 |

https://github.com/DataForGEO/mcp

### Agent Skills

开箱即用的 GEO 工作流，适用于 Claude Code、Claude.ai 以及其他支持 Agent Skills 的 agent（Codex CLI、Cursor、Gemini CLI 等）。会花 credits 的 skill 都会先查余额、估算预占，征得你同意后才批量调用。每个 skill 自带零依赖的命令行工具 dfgeo.py，只需 Python 3.8+。

```text
/plugin marketplace add DataForGEO/skills
/plugin install dataforgeo@dataforgeo
```

| skill | 说明 | 花 credits |
| --- | --- | --- |
| `dataforgeo-api` | 基础：单次调用 answer / index / summary、查余额、估算 credits、取异步任务 | 按调用 |
| `geo-prompt-set-builder` | 按意图 × 人群 × 语言设计要追踪的 prompt 集，输出 JSONL 并估算成本 | 否 |
| `geo-visibility-audit` | 品牌 AI 可见度体检：批量跑 prompt × 引擎，出带依据和行动建议的报告 | 是，先估算并征得同意 |
| `geo-competitor-benchmark` | 竞品对比：声量份额、首推率、平均位次、逐 prompt 胜负 | 是，同上 |
| `geo-citation-audit` | 引用来源分析：AI 引用了哪些站点、自有来源引用率、内容 / 外联 / PR 清单 | 可复用已有结果，不额外扣费 |
| `geo-index-report` | GEO Index 周报 / 月报，并搭建固定 tag 的每周追踪 | 报告否；追踪按调用 |

Claude.ai / Claude Desktop：在仓库里运行 python3 scripts/package.py 生成 zip，到 设置 → 功能 → Skills 上传，并开启代码执行。Skills 和 MCP 可以一起用。

https://github.com/DataForGEO/skills

### SDK

TypeScript / JavaScript 包 @dataforgeo/client，Python 包 dataforgeo。

```bash
npm install @dataforgeo/client
pip install dataforgeo
```

```ts
import { DataForGEO } from "@dataforgeo/client";

const client = new DataForGEO(); // reads DATAFORGEO_API_KEY
const res = await client.geo.answer({
  prompt: "东京有哪些适合家庭入住的民宿？",
  engines: ["chatgpt"],
  brand: "晓宅",
  location: "JP",
  language: "zh-CN",
});
console.log(res.answers[0].brand?.mentioned, res._meta.creditsRemaining);
```

```python
from dataforgeo import DataForGEO

client = DataForGEO()  # reads DATAFORGEO_API_KEY
res = client.geo.answer(
    prompt="东京有哪些适合家庭入住的民宿？",
    engines=["chatgpt"],
    brand="晓宅",
    location="JP",
    language="zh-CN",
)
print(res["answers"][0]["brand"]["mentioned"], res.meta.credits_remaining)
```

- 两个 SDK 的接口一一对应，覆盖全部接口、错误码、用量响应头（x-credits-used 等）、异步任务和 webhook 签名校验。
- 请求参数和响应字段与 API 一致（snake_case），不做转换。
- 429、408、5xx 自动重试（错误响应不扣费）；网络错误只重试 GET，POST 不重试以免重复扣费。

https://github.com/DataForGEO/client


## 计费与 credits

只对实际返回的答案扣费；请求开始时按「prompt × 引擎 × 采样数」预占 credits，结束后多退少补。credits 一次性购买、永不过期。

| 调用 | 每条答案扣费 |
| --- | --- |
| GEO 数据，标准引擎（chatgpt、google-aio、chatgpt-api、perplexity、grok） | 1 |
| GEO 数据，高成本引擎（gemini、gemini-api、claude） | 2 |
| Index 分析（/v1/geo/index 在答案上计算 KPI） | +1 |
| 缓存命中 | 0 |
| 引擎超时、失败或无答案 | 0 |
| 503 engines_unavailable（请求的引擎全部不可用） | 0 |
| /v1/geo/index/summary、/v1/jobs、/v1/account、/v1/status | 0 |

### 响应头

| 响应头 | 含义 |
| --- | --- |
| `x-credits-used` | 本次请求实际扣除的 credits |
| `x-credits-remaining` | 扣除后的余额 |
| `x-cache` | hit、miss 或 partial（多条答案中部分命中） |

### 缓存

缓存键为 prompt + 引擎 + 地区 + 语言 + 采样序号，有效期 24 小时，跨账户共享。传 fresh: true 跳过缓存，按正常价格扣费。


## 引擎与地区

engines 参数接受下面 8 个 id，一次请求可传多个；每个引擎单独计费、单独返回。引擎分两种答案类型：产品答案是真实用户在该 AI 产品界面里看到的答案；模型答案是模型经 API 并开启自带联网搜索后给出的答案。

| 引擎 id | 平台 | 答案类型 | 每条答案扣费 |
| --- | --- | --- | --- |
| `chatgpt` | ChatGPT | 产品答案 | 1 |
| `gemini` | Gemini | 产品答案 | 2 |
| `google-aio` | Google AI Overview | 产品答案 | 1 |
| `chatgpt-api` | ChatGPT API | 模型答案 | 1 |
| `gemini-api` | Gemini API | 模型答案 | 2 |
| `claude` | Claude | 模型答案 | 2 |
| `perplexity` | Perplexity | 模型答案 | 1 |
| `grok` | Grok | 模型答案 | 1 |

- 产品答案：chatgpt、gemini、google-aio。模型答案：chatgpt-api、gemini-api、claude、perplexity、grok。
- chatgpt 与 chatgpt-api、gemini 与 gemini-api 是不同的引擎：同一个问题，产品界面和 API 给出的答案、引用来源都可能不同，KPI 和趋势也分开统计。想看用户实际看到什么用产品答案；想要可复现、按模型版本对比用模型答案。
- 某个引擎不可用时，它的答案直接标为失败，不会改用另一种答案类型顶替，所以同一个引擎 id 下的数据口径始终一致。
- location：ISO 3166-1 两位国家代码，例如 JP、US；决定搜索结果和 AI Overview 的地区。默认 US。
- language：BCP 47 语言代码，例如 ja、zh-CN、en。默认按 location 推断。
- google-aio 只在搜索结果出现 AI Overview 时返回答案；没出现时 status 为 no_answer，不扣费。


## 获取 AI 答案

`POST https://api.dataforgeo.dev/v1/geo/answer` · all plans

拿一个 prompt 在多个引擎上的 AI 答案，并标出品牌提及、引用来源和竞品实体。所有档位可用。

### 参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `prompt` | string | 是 | 要问的问题，最长 2,000 字符 |
| `engines` | string[] | 是 | 引擎 id 列表，见「引擎与地区」 |
| `brand` | string | 否 | 要识别的品牌名；不传则只返回答案和实体 |
| `brand_variants` | string[] | 否 | 品牌别名，例如片假名、英文名 |
| `competitors` | string[] | 否 | 竞品名，最多 20 个 |
| `location` | string | 否 | 国家代码，默认 US |
| `language` | string | 否 | 语言代码，默认按 location 推断 |
| `samples` | integer | 否 | 每个引擎采样次数，1–10，默认 1 |
| `fresh` | boolean | 否 | true 时跳过缓存，默认 false |
| `async` | boolean | 否 | true 时立即返回 job_id，见「异步任务与账户」 |
| `webhook_url` | string | 否 | 异步完成后回调的地址 |

### 请求示例

```bash
curl https://api.dataforgeo.dev/v1/geo/answer \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "东京有哪些适合家庭入住的民宿？",
    "engines": [
      "chatgpt"
    ],
    "brand": "晓宅",
    "location": "JP",
    "language": "zh-CN"
  }'
```

### 响应示例

```json
{
  "request_id": "req_8f2c1a",
  "prompt": "东京有哪些适合家庭入住的民宿？",
  "credits_used": 1,
  "answers": [
    {
      "engine": "chatgpt",
      "sample": 1,
      "status": "ok",
      "cached": false,
      "generated_at": "2026-11-02T00:31:12Z",
      "text": "……",
      "brand": {
        "mentioned": true,
        "mention_count": 2,
        "first_position": 3,
        "sentiment": "positive"
      },
      "entities": [
        {
          "name": "晓宅",
          "type": "brand",
          "position": 3,
          "is_competitor": false
        },
        {
          "name": "Example Stay",
          "type": "brand",
          "position": 1,
          "is_competitor": true
        }
      ],
      "citations": [
        {
          "url": "https://example.com/guide",
          "domain": "example.com",
          "position": 1,
          "is_brand_domain": false
        }
      ]
    }
  ]
}
```

- status 取值：ok、no_answer、timeout、failed；后三种不扣费。
- status 为 timeout 或 failed 时，答案多一个 error 字段说明原因，取值见下表；ok 和 no_answer 的答案没有这个字段。
- first_position 是品牌在答案推荐列表中第一次出现的位次，未出现时为 null。

### 答案的 error 字段

| error | 含义 |
| --- | --- |
| `upstream_timeout` | 引擎在时限内没有给出答案（已自动重试） |
| `upstream_error` | 引擎返回错误，自动重试后仍失败 |
| `engine_unavailable` | 该引擎暂时不可用，没有发出调用；可在 /v1/status 查看状态 |

### 失败的答案示例

```json
{
  "engine": "grok",
  "sample": 1,
  "status": "failed",
  "error": "engine_unavailable",
  "cached": false
}
```


## 计算 GEO Index

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

在 /v1/geo/answer 的结果上计算 GEO Index 的 KPI。Pro、Scale、Enterprise 可用；Starter 调用返回 403 plan_not_allowed。

### 参数

参数与 /v1/geo/answer 相同，brand 改为必填，另加：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `brand` | string | 是 | 要计算 KPI 的品牌 |
| `tag` | string | 否 | 自定义分组标签，例如 osaka-family-q4；/summary 按它汇总 |
| `intent` | string | 否 | prompt 意图：compare、cost、discover、evaluate、howto、recommend |
| `persona` | string | 否 | 提问人群，自由文本，例如 带孩子的家庭 |

### 请求示例

```bash
curl https://api.dataforgeo.dev/v1/geo/index \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "大阪带孩子住哪里方便？",
    "engines": [
      "chatgpt",
      "perplexity",
      "grok"
    ],
    "brand": "晓宅",
    "tag": "osaka-family-q4",
    "intent": "recommend",
    "persona": "带孩子的家庭",
    "location": "JP",
    "language": "zh-CN"
  }'
```

### 响应示例

```json
{
  "request_id": "req_91d0b3",
  "brand": "晓宅",
  "tag": "osaka-family-q4",
  "credits_used": 6,
  "answers": [
    "…与 /v1/geo/answer 相同…"
  ],
  "kpis": {
    "visibility": {
      "value": 0.667,
      "numerator": 2,
      "denominator": 3,
      "samples": 3
    },
    "share_of_voice": {
      "value": 0.25,
      "numerator": 2,
      "denominator": 8,
      "samples": 3
    },
    "top_rate": {
      "value": 0,
      "numerator": 0,
      "denominator": 3,
      "samples": 3
    },
    "competitor_gap": {
      "value": -1.33,
      "samples": 3
    },
    "positive_ratio": {
      "value": 1,
      "numerator": 2,
      "denominator": 2,
      "samples": 3
    }
  },
  "kpi_tier": "pro"
}
```

- 上例为 3 个标准引擎各 1 条答案：3 × 1 credit + 3 × 1 credit Index = 6 credits。
- kpi_tier 为 pro 时只返回核心 KPI；scale 时返回全部 KPI。
- 单次请求的样本量小，KPI 仅供参考；趋势和对比请用 /v1/geo/index/summary。


## 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 和标签。


## 异步任务与账户

多引擎、多采样的请求可能要等一两分钟，建议传 async: true：接口立即返回 job_id，结果用轮询或 webhook 取回。同步请求超过 120 秒会自动转为异步，并返回 202。

### 接口

| 接口 | 说明 | credits |
| --- | --- | --- |
| `GET /v1/jobs/{job_id}` | 查询任务状态和结果 | 0 |
| `GET /v1/account` | 查询余额、档位、本月用量 | 0 |

### 异步请求的响应

```json
{
  "job_id": "job_3b7e90",
  "status": "queued",
  "credits_held": 9
}
```

`GET /v1/account`

```json
{
  "plan": "scale",
  "credits_remaining": 10422,
  "credits_used_this_month": 1578
}
```

- status 依次为 queued、running、completed 或 failed；completed 时 result 字段与同步响应相同。
- 异步请求里 timeout 或 failed 的答案会在约 2 分钟后自动补跑一轮，仍失败才定为最终结果；同步请求不补跑。
- credits_held 是预占的 credits，完成后按实际返回的答案结算，多余部分退回。
- 传了 webhook_url 时，完成后向该地址 POST 完整结果，请求头带 x-dataforgeo-signature（HMAC-SHA256，密钥在控制台查看），用于验证来源。
- 任务结果保留 7 天。


## 引擎状态

`GET https://api.dataforgeo.dev/v1/status` · public, no auth

返回每个引擎此刻的状态、过去 24 小时的成功率和中位延迟、过去 30 天每天的可用率。免鉴权、不扣费，可以在发请求前先查哪些引擎可用；官网状态页用的也是这份数据。

### 请求示例

```bash
curl "https://api.dataforgeo.dev/v1/status"
```

### 响应示例

```json
{
  "updated_at": "2026-11-02T05:40:00Z",
  "status": "degraded",
  "engines": [
    {
      "id": "chatgpt",
      "name": "ChatGPT",
      "answer_type": "product",
      "status": "operational",
      "last_24h": {
        "success_rate": 0.987,
        "median_latency_ms": 21400,
        "calls": 1234
      },
      "daily": [
        {
          "date": "2026-10-04",
          "uptime": 0.998
        },
        "… 30 项 …",
        {
          "date": "2026-11-02",
          "uptime": 1
        }
      ]
    },
    {
      "id": "claude",
      "name": "Claude",
      "answer_type": "model",
      "status": "degraded",
      "last_24h": {
        "success_rate": 0.912,
        "median_latency_ms": 9800,
        "calls": 640
      },
      "daily": [
        "…"
      ]
    },
    {
      "id": "grok",
      "name": "Grok",
      "answer_type": "model",
      "status": "unavailable",
      "last_24h": {
        "success_rate": 0.64,
        "median_latency_ms": 7300,
        "calls": 210
      },
      "daily": [
        "…"
      ]
    },
    "…"
  ]
}
```

### engines[].status 取值

| status | 含义 |
| --- | --- |
| `operational` | 正常 |
| `degraded` | 降级：近 15 分钟成功率低于 90%，请求仍会发出，但失败可能变多 |
| `unavailable` | 不可用：该引擎的答案会直接返回 failed / engine_unavailable，不扣费 |

- 顶层 status 汇总全部引擎：全部 unavailable 时为 outage；有任一引擎 degraded 或 unavailable 时为 degraded；否则 operational。
- last_24h 统计过去 24 小时的真实调用：success_rate 为 0–1 的小数，median_latency_ms 为中位延迟，calls 为调用次数；没有调用时前两项为 null。google-aio 返回 no_answer 算成功，缓存命中不计入。
- daily 固定 30 项，按 UTC 日期从旧到新，最后一项是今天；当天没有调用时 uptime 为 null。
- 免鉴权，允许跨域（CORS *），响应缓存 30 秒；数据每 5 分钟汇总一次。网页版见 dataforgeo.dev/status。


## KPI 字段参考

Pro 返回 11 个核心 KPI，Scale 与 Enterprise 另加 8 个高阶 KPI。这里只给公开定义，不公开计算方法。

| 字段 | 名称 | 定义 | 单位 | 档位 | 返回位置 |
| --- | --- | --- | --- | --- | --- |
| `findability` | 综合可发现度 | 品牌在 AI 答案中被发现、被推荐程度的综合分 | 分 | pro | 单次与汇总 |
| `visibility` | 可见度 | 出现品牌的答案占比 | 比例 | pro | 单次与汇总 |
| `own_mentions` | 自有提及数 | 平均每条答案提到品牌的次数 | 次 | pro | 单次与汇总 |
| `citations` | 引用数 | 平均每条答案引用的来源数 | 次 | pro | 单次与汇总 |
| `citation_rate` | 引用率 | 引用了品牌自有来源的答案占比 | 比例 | pro | 单次与汇总 |
| `share_of_voice` | 声量份额 | 品牌提及占品牌加竞品提及的比例 | 比例 | pro | 单次与汇总 |
| `competitor_mentions` | 竞品提及数 | 平均每条答案提到竞品的次数 | 次 | pro | 单次与汇总 |
| `competitor_gap` | 竞品差距 | 自有提及数减竞品提及数 | 次 | pro | 单次与汇总 |
| `top_rate` | 首推率 | 品牌排在推荐第一位的答案占比 | 比例 | pro | 单次与汇总 |
| `positive_ratio` | 正面比例 | 品牌提及中正面评价的占比 | 比例 | pro | 单次与汇总 |
| `tone` | 语气得分 | 提及品牌时的整体语气，-1 到 1 | 分 | pro | 单次与汇总 |
| `weighted_share` | 加权份额 | 按提及位置加权后的声量份额 | 比例 | scale | 仅汇总 |
| `rank_gap` | 排名差距 | 与每个竞品的推荐位次差，按竞品分别返回 | 位 | scale | 单次与汇总 |
| `recommendation_position` | 推荐位次指数 | 品牌在推荐列表中位置的得分 | 分 | scale | 单次与汇总 |
| `purchase_intent_rate` | 购买意向推荐率 | 购买意向类问题中品牌被推荐的比例 | 比例 | scale | 单次与汇总 |
| `conclusion_bias` | 结论推荐倾向 | 答案结论是推荐还是劝退品牌，-1 到 1 | 分 | scale | 单次与汇总 |
| `category_capture_gap` | 品类捕获差 | 品牌在所属品类问题中的捕获差距 | 分 | scale | 仅汇总 |
| `knowledge_half_life` | AI 知识半衰期 | AI 对品牌认知的衰减周期 | 周 | scale | 仅汇总 |
| `features` | 特征提及 | 答案中提到的品牌卖点列表 | 列表 | scale | 单次与汇总 |

- 比例类字段取值 0 到 1；带 numerator 和 denominator 的字段可以直接核对。
- purchase_intent_rate 只统计 intent 为购买意向的 prompt，请求时需带 intent。


## 错误码与限制

出错时返回统一结构，且不扣费。单个引擎失败不会让整个请求报错：该条答案的 status 为 timeout 或 failed，error 字段说明原因，不扣费，其余引擎照常返回。只有请求的引擎全部不可用时，整个请求才返回 503。

| HTTP | code | 含义 |
| --- | --- | --- |
| 400 | `invalid_request` | 参数缺失或格式错误，message 指出具体字段 |
| 400 | `unsupported_engine` | engines 里有不认识的引擎 id |
| 401 | `invalid_api_key` | API key 缺失、错误或已停用 |
| 402 | `insufficient_credits` | 余额不够预占本次请求 |
| 403 | `plan_not_allowed` | 当前档位不能用该接口或参数，例如 Starter 调用 index、Pro 使用 group_by |
| 404 | `not_found` | job_id 不存在或已过期 |
| 500 | `internal_error` | 服务端错误，可用 request_id 联系支持 |
| 503 | `engines_unavailable` | 请求的引擎全部暂时不可用；响应带 Retry-After（秒），不预占、不扣费。只要有一个引擎可用，请求就照常处理 |

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "本次请求需预占 9 credits，余额 4",
    "request_id": "req_7a11c2"
  }
}
```

```json
{
  "error": {
    "code": "engines_unavailable",
    "message": "请求的引擎当前都不可用：claude、grok",
    "request_id": "req_5c02e4"
  }
}
```

### 限制

- 不设账户级速率限制；为保证稳定，建议并发不超过 100 个请求（待压测确定）。
- 每个请求最多 8 个引擎 × 10 次采样 = 80 条答案。
- 引擎的临时错误（网络错误、超时、限流、5xx）会在时限内自动重试，最多 2 次；重试不额外扣费。
- prompt 最长 2,000 字符；competitors 最多 20 个。
- 缓存 24 小时，异步任务结果保留 7 天。