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

# Citation Analysis

> 针对单个提示词的 AI 可见度诊断：引擎执行的搜索、检索与引用的页面、回答提及的品牌及其背后的页面、你的品牌所处位置，以及按优先级排列的行动建议

将一个已完成的 AI 回答与其背后的页面进行比对。结果展示引擎执行的搜索、它检索到的页面和其中被引用的页面、
回答提及的品牌以及提及这些品牌的页面、你的品牌所处的位置，以及按优先级排列的行动建议。它还会把每个被引用页面的段落
对应到回答中的相应部分，为每条关联附上说明，并总结被引用页面的共同点。

这是对已有回答的事后对应分析，不能证明某个来源促使模型生成了某句话，也不是对页面质量的评分。
请把它当作需要检查的证据，而不是结论。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/citation-analysis \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "answer": "…the AI answer, as raw markdown…",
    "prompt": "best password manager for a small team",
    "engine": "CHATGPT",
    "brand": "1Password",
    "competitors": ["Bitwarden"],
    "citations": [
      { "url": "https://example.com/best-password-managers", "body": "…the page markdown…" },
      { "url": "https://another.example.com/pricing" }
    ]
  }'
```

轮询 `GET /v1/async/task/:id`，或在提交时提供 `webhook.url`；任务报告为 `taskType: "CITATION_ANALYSIS"`。
不要通过 `POST /v1/async/task` 提交此分析，请使用专用端点。旧端点（包括 GEO Audit 时期的名称）`POST /v1/geo-audit`、`POST /v1/source-influence` 和 `POST /v1/research`、
任务类型 `GEO_AUDIT`、`SOURCE_INFLUENCE` 和 `CITATION_ATTRIBUTION` 以及 `include.geoAudit`、`include.sourceInfluence` 仍然可用；响应始终使用新名称。

### 分析你已运行过的任务

如果回答来自本 API，请直接发送它的任务 id，而不是从结果中复制回答和引用：

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/citation-analysis \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "taskId": "7c1f…", "brand": "1Password", "competitors": ["Bitwarden"] }'
```

该任务必须属于你、状态为 `COMPLETED`，并且仍可通过 `GET /v1/async/task/:id` 读取。它的回答 Markdown（引擎未返回
Markdown 时为文本）成为 `answer`，其引用 URL 按引擎顺序成为 `citations`：取前 100 个，其中讨论帖最多 10 个。
商品和视频卡片占位符（`googleusercontent.com` 链接）以及 Google 搜索链接会被跳过，因为它们没有可读取的页面。
除非你另行发送，否则使用该任务的 `prompt`、`country` 和引擎。将 `taskId` 与 `answer` 或 `citations` 一起发送会以
`400` 拒绝；未完成、没有回答文本或引用 URL 的任务同样如此。未知或已过期的任务 id 返回 `404`。

### 在采集时分析每一条回答

在采集请求中加入 `include.citationAnalysis: true`，回答采集完成后会立即运行分析。适用于回答引擎(`CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE_AIO`, `GOOGLE_AIMODE`, `NAVER_AI_BRIEF`, `NAVER_AI_TAB`, `BING_SEARCH`, `BING_COPILOT`)，
单个任务、任务批量、网格和 `POST /v1/batches` 均可使用。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "taskType": "CHATGPT",
    "payload": { "prompt": "best password manager for a small team", "country": "US", "include": { "citationAnalysis": true } },
    "webhook": { "url": "https://example.com/hook" }
  }'
```

分析读取回答及其引用 URL 的方式与上文的 `taskId` 相同。随后回答结果中会带有 `response.citationAnalysis`：
即 `GET /v1/async/task/:id` 返回的分析任务本身，包含 `task`、`credits` 以及 `response` 或 `error`。

* **Webhook**：在分析完成后发送一次，同时包含回答和分析。
* **轮询**：回答一就绪，回答任务即为 `COMPLETED`。请继续轮询，直到 `response.citationAnalysis.task.status` 为 `COMPLETED` 或 `FAILED`。
* **批量**在所有回答及其分析都结束后才完成。
* **没有分析时**：如果回答没有可读取的引用 URL，或者积分或密钥的每日上限不足以预留分析所需的额度，`response.citationAnalysis` 为 `{ "error": "…" }`，回答会立即送达。
* **计费**：分析与其他Citation Analysis任务一样按用量单独计费，回答的扣费不变。仅允许特定任务类型的密钥也需要允许 `CITATION_ANALYSIS`。

## Payload

| 字段 | 必填 | 说明 |
| - | - | - |
| `taskId` | 替代 `answer` + `citations` | 你已完成的回答任务，见上文。 |
| `answer` | 是（无 `taskId` 时） | 原始回答 Markdown，1–200,000 个字符。请保持不变；所有范围都是这段文本的 UTF-16 偏移量。 |
| `citations[]` | 是（无 `taskId` 时） | 引擎引用的页面，也可附加引擎检索到但未引用的页面：被引用的最多 100 个、未被引用的最多 50 个，至少一个被引用，讨论帖 URL 最多 10 个。 |
| `citations[].url` | 是 | HTTP(S) URL，最多 2,048 个字符。 |
| `citations[].body` | 否 | 来源 Markdown，每条引用最多 300,000 个字符；整个请求正文最多 1 MiB。提供的正文按原样分析，不会被重新抓取的内容替换。未提供正文时我们会抓取页面；无法读取的页面会在该来源上以 `error` 报告。 |
| `citations[].kind` | 否 | `inline` 或 `panel`；省略时根据回答中的链接判断。 |
| `citations[].cited` | 否 | 默认为 `true`。`false` 表示引擎检索到（搜索结果）但未引用的页面。 |
| `citations[].position` | 否 | 整数 ≥ 1：引擎自身在搜索结果中给该页面的排名。 |
| `citations[].query` | 否 | 找到该页面的搜索（≤ 500 个字符）；若 `queries` 中没有则会被加入。 |
| `citations[].citedText[]` | 否 | 引擎自身报告引用的段落，最多 20 段（每段 ≤ 2,000 个字符）。 |
| `citations[].publishedAt` | 否 | 引擎报告的发布日期，≤ 64 个字符。 |
| `queries[]` | 否 | 引擎执行的搜索，最多 20 个，每个 ≤ 500 个字符。 |
| `prompt` | 否 | 原始问题。 |
| `engine` | 否 | 生成回答的 AI 引擎。 |
| `brand` | 否 | 你的品牌名。提供后，结果会增加 `visibility` 和 `actions`。 |
| `brandDomains[]` | 否 | 你品牌自有站点的主机名，最多 10 个，例如 `coway.com`。只接受不带协议和路径、由字母、数字、点和连字符组成、不超过 253 个字符的主机名。需要同时提供 `brand`，否则请求会以 `422` 被拒绝。未提供 `brandDomains` 时，主机名中包含品牌名的站点视为品牌自有站点。 |
| `brandAliases[]` | 否 | 你品牌的其他名称（产品线、本地拼写），最多 10 个，每个 ≤ 200 个字符。需要同时提供 `brand`，否则请求会以 `422` 被拒绝。 |
| `competitors[]` | 否 | 最多 25 个竞争对手名称，在 `brands` 中以 role `competitor` 报告。 |
| `country` | 否 | 抓取来源时使用的国家，默认 `US`。 |

使用 `taskId` 或 `include.citationAnalysis` 时，这些字段由回答的原始数据填充。对于 `CHATGPT`，引擎的搜索成为 `queries`，
它检索到的每个页面都成为一条带有 `cited`、`position`、`citedText`、`publishedAt` 和 `query` 的引用；仅跟踪参数不同的
同一 URL 会被合并。对于 Google AI Overview，概览中的来源为被引用，其外的自然搜索结果为未被引用，`position` 为其自然排名。
其他引擎只提供被引用的来源。

> [!WARNING]
>
> 请求包含 `analysis` 时会返回 `400`。每个结果都包含洞察。

## 结果

v4 之前存储的结果保持原有结构，不含 `version` 字段。

```json theme={"theme":"css-variables"}
{
  "version": 4,
  "answer": "For most homes, the Coway Airmega 250 is the best all-round pick. Levoit Core 300 is a strong budget choice, and Blueair Blue Pure 211+ suits large rooms.",
  "queries": [
    { "id": "q0", "text": "best air purifiers 2026 reviews", "sourceIds": ["s0", "s1", "s2"] }
  ],
  "sources": [
    {
      "id": "s0",
      "url": "https://www.example-reviews.com/best-air-purifiers",
      "domain": "example-reviews.com",
      "channel": "editorial",
      "cited": true,
      "position": 1,
      "queryIds": ["q0"],
      "publishedAt": "October 7, 2026",
      "citedText": ["Levoit Core 300 is the best budget purifier we tested."],
      "brandIds": ["b1", "b2"],
      "own": false,
      "paragraphs": [
        { "id": "s0p0", "text": "Levoit Core 300 is the best budget purifier we tested." },
        { "id": "s0p1", "text": "For large rooms, the Blueair Blue Pure 211+ cleared the air fastest." }
      ]
    },
    {
      "id": "s1",
      "url": "https://www.coway.com/airmega-250",
      "domain": "coway.com",
      "channel": "own",
      "cited": false,
      "position": 4,
      "queryIds": ["q0"],
      "publishedAt": null,
      "citedText": [],
      "brandIds": ["b0"],
      "own": true,
      "paragraphs": []
    },
    {
      "id": "s2",
      "url": "https://www.reddit.com/r/AirPurifiers/comments/abc123/budget_pick",
      "domain": "reddit.com",
      "channel": "community",
      "cited": true,
      "position": 6,
      "queryIds": ["q0"],
      "publishedAt": null,
      "citedText": [],
      "brandIds": ["b1"],
      "own": false,
      "paragraphs": [
        { "id": "s2p0", "text": "Two years with the Levoit Core 300 and it is still quiet on sleep mode." }
      ]
    }
  ],
  "brands": [
    { "id": "b0", "name": "Coway", "role": "target", "rank": 1, "answerRanges": [{ "start": 20, "end": 25 }], "citedSourceIds": [], "retrievedSourceIds": ["s1"], "ownSourceIds": ["s1"] },
    { "id": "b1", "name": "Levoit", "role": "competitor", "rank": 2, "answerRanges": [{ "start": 66, "end": 72 }], "citedSourceIds": ["s0", "s2"], "retrievedSourceIds": [], "ownSourceIds": [] },
    { "id": "b2", "name": "Blueair", "role": "answer", "rank": 3, "answerRanges": [{ "start": 113, "end": 120 }], "citedSourceIds": ["s0"], "retrievedSourceIds": [], "ownSourceIds": [] }
  ],
  "links": [
    { "id": "l0", "paragraphId": "s0p0", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Names the Levoit Core 300 as the budget pick." },
    { "id": "l1", "paragraphId": "s0p1", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Recommends the Blueair Blue Pure 211+ for large rooms." },
    { "id": "l2", "paragraphId": "s2p0", "answerRanges": [{ "start": 66, "end": 154 }], "explanation": "Reports long-term use of the Levoit Core 300." }
  ],
  "visibility": { "brandId": "b0", "stage": "mentioned", "rank": 1, "answerBrands": 3 },
  "actions": [
    {
      "id": "a0",
      "type": "improve_page",
      "control": "owned",
      "priority": 1,
      "summary": "Coway's Airmega 250 page was retrieved for this search but not cited.",
      "steps": [
        "Add a table of room coverage, noise level and yearly filter cost, the criteria the cited review compares.",
        "Show when the specifications were last updated."
      ],
      "sourceIds": ["s1"],
      "brandIds": ["b0"],
      "queryIds": ["q0"],
      "linkIds": []
    },
    {
      "id": "a1",
      "type": "publish_page",
      "control": "owned",
      "priority": 2,
      "summary": "No Coway page was cited for this search; the cited review is a dated buying guide.",
      "steps": [
        "Publish a 2026 air purifier buying guide on coway.com, organized by room size and budget.",
        "Explain how models were compared, show measured results, and name the author and date."
      ],
      "sourceIds": ["s0"],
      "brandIds": ["b0"],
      "queryIds": ["q0"],
      "linkIds": ["l0", "l1"]
    },
    {
      "id": "a2",
      "type": "post_on_platform",
      "control": "platform",
      "priority": 3,
      "summary": "A cited Reddit thread recommends Levoit and never mentions Coway.",
      "steps": [
        "Reply as an identified Coway representative with the Airmega 250 details the thread asks about."
      ],
      "sourceIds": ["s2"],
      "brandIds": ["b1"],
      "queryIds": ["q0"],
      "linkIds": ["l2"]
    },
    {
      "id": "a3",
      "type": "pitch_publisher",
      "control": "outreach",
      "priority": 4,
      "summary": "The top cited review names Levoit and Blueair but not Coway; only its publisher can add the Airmega 250.",
      "steps": [
        "Offer the editors an Airmega 250 for testing.",
        "Send test data for the criteria the review uses: room coverage, noise and filter cost."
      ],
      "sourceIds": ["s0"],
      "brandIds": ["b1", "b2"],
      "queryIds": ["q0"],
      "linkIds": ["l0", "l1"]
    }
  ],
  "insights": [
    { "summary": "Both cited pages recommend Levoit for a budget; the review also backs Blueair for large rooms.", "sourceIds": ["s0", "s2"], "linkIds": ["l0", "l1", "l2"] },
    { "summary": "The answer names Coway first, yet no cited page names it; only its own page, which was not cited, does.", "sourceIds": ["s1"], "linkIds": [] }
  ]
}
```

### `version`

此结构始终为 `4`。

### `answer`

原样返回你提交的回答。`answerRanges` 是这个字符串的偏移量：JavaScript UTF-16 码元，`start` 包含，`end` 不包含。
请直接截取，即 `answer.slice(start, end)`，不要重新切分文本。`links[]` 的每个范围对应回答中一个完整的语义单元：
句子、列表项或表格单元格；`brands[]` 的每个范围就是原样书写的名称。边界以原文为准。

### `queries[]`

引擎为该回答执行的搜索。每项包含 `id`、搜索 `text`，以及 `sourceIds`：该搜索找到的来源。引擎未公开搜索且你也未发送时为空。

### `sources[]`：每个页面一项

* `id`：不透明标识符，在结果内唯一。
* `url`：页面 URL；`domain`：其主机名。
* `channel`：页面由谁控制，根据其主机名判断：
  * `own`：你品牌的自有站点（恰好在 `own` 为 `true` 时）。
  * `brand`：结果中提及的其他品牌的自有站点。
  * `editorial`：发布方；只有发布方能修改该页面。无法识别的主机名报告为 `editorial`。
  * `retailer`：网店或电商平台。
  * `review_platform`：消费者或企业点评网站。
  * `community`：论坛或问答网站。
  * `video`：视频平台。
  * `social`：社交网络。
  * `blog_platform`：托管博客服务。
  * `reference`：百科或 wiki；绝不会成为行动的对象。
* `cited`：回答引用了该页面时为 `true`，引擎仅检索到时为 `false`。
* `position`：引擎自身给该页面的排名，未提供时为 `null`。
* `queryIds[]`：找到该页面的搜索。
* `publishedAt`：引擎报告的发布日期，或 `null`。
* `citedText[]`：引擎自身报告引用的段落；没有时为 `[]`。
* `brandIds[]`：在可读页面、其标题或 `citedText` 中提及的品牌。
* `own`：页面位于你品牌自有站点时为 `true`。
* `paragraphs[]`：结果中包含的被引用页面的段落。每个段落有一个 `id`（在整个结果中全局唯一）和段落 `text`。
  段落也可能在没有任何关联的情况下被包含。未被引用的页面始终为空。
* `error`：仅在页面无法读取时出现。此时 `paragraphs` 为空，字符串是该来源的简短原因。

### `brands[]`

结果跟踪的所有品牌：你的 `brand`（`role: "target"`）、你的 `competitors`（`"competitor"`），以及回答提及的其他品牌（`"answer"`）。

* `rank`：该品牌名称在回答中首次出现的顺序，从 1 开始；回答未提及该品牌时为 `null`。
* `answerRanges[]`：回答中提及该品牌或其产品名称的精确位置，使用相同的 UTF-16 偏移量，`answer.slice(start, end)` 返回原样书写的名称。匹配不区分大小写，按整词匹配（不使用空格分词的文字除外），包括标题和表格单元格，但不包括链接 URL 或图片标记内部。与 `links[]` 的范围不同，它们不是完整的回答单元。
* `citedSourceIds[]`：页面提及该品牌的被引用来源。
* `retrievedSourceIds[]`：页面提及该品牌的未被引用来源。
* `ownSourceIds[]`：位于该品牌自有站点的来源；仅对 target 填充。

### `links[]`：每个段落一条关系

* `paragraphId`：这条关联所指的段落，始终指向 `sources[]` 中存在的段落。
* `answerRanges[]`：该段落对应的回答部分，以与上文相同的 UTF-16 偏移量给出 `start`/`end` 对。一条关联可以有多个
  范围，同一段回答文本不会在范围之间重复。每个范围都是完整的回答单元（句子、列表项或表格单元格）。
* `explanation`：描述对应关系的一句简短说明：该段落对回答的这一部分说了什么。

### `visibility`

你的品牌在该回答中所处的位置；未发送 `brand` 时为 `null`。

* `brandId`：你的品牌在 `brands[]` 中的 id。
* `stage`：以下之一：
  * `mentioned`：回答提及了你的品牌。
  * `on_cited_page`：回答未提及，但某个被引用页面提及了。
  * `on_retrieved_page`：只有引擎检索到但未引用的页面提及了。
  * `not_found`：所有已读取的页面都未提及。
* `rank`：你的品牌在 `brands[]` 中的 `rank`。
* `answerBrands`：回答提及的品牌数量。

### `actions[]`

针对你品牌的按优先级排列的下一步行动；未发送 `brand` 时为 `[]`。`priority` 从 1（最先执行）开始且连续无间隔。
行动按 `control` 排序：先是你的品牌可控制的（`owned`），然后是品牌可以发帖的平台（`platform`），最后是外联（`outreach`）。
`summary` 是一句话，`steps[]` 包含一到五个具体步骤，两者都以回答的语言写成。`sourceIds`、`brandIds`、`queryIds` 和
`linkIds` 指向本结果中的证据。

| `type` | `control` | 出现条件 | `sourceIds` |
| - | - | - | - |
| `improve_page` | `owned` | 每个自有站点一项：该站点上你的页面被检索到但未被引用，或被引用了但回答没有提及你的品牌。步骤说明要添加或修改什么，使页面像被引用页面那样回答提示词：标准、数据、时效性。 | 该站点上你的最多 3 个页面，未被引用的页面在前。 |
| `publish_page` | `owned` | 针对没有任何你的页面被引用的搜索：一份在你自有站点上新建页面的简要方案，以被引用页面为参照，包括页面类型和标题、章节和标准、要展示的证据、日期，以及明确的品牌署名。 | 作为参照的被引用页面。 |
| `post_on_platform` | `platform` | 零售商、点评平台、社区、视频、社交或博客平台上的某个页面提及了竞争品牌，但没有提及你的品牌。行动是用你自己的账号在该平台上发布品牌自己的商品信息、主页、回答或帖子：上架或完善你的产品、认领你的主页并邀请真实客户评价、以明确的品牌代表身份回复，或发布演示或对比内容。它从不要求平台或页面所有者做任何事。每个域名最多一项。 | 该平台上被引用的页面（属于他人）。 |
| `pitch_publisher` | `outreach` | 某个被引用的编辑类页面提及了竞争品牌但没有提及你的品牌，或提及了你的品牌而回答没有。只有发布方能修改该页面；步骤说明要发送什么。 | 要联系推荐的页面。 |

`brandIds` 指明你的品牌，或这些页面提及的竞争品牌。行动绝不会建议虚假或未披露的评价、冒充独立评测者、购买链接，
或编辑不属于你品牌的页面。提及你品牌但未被引用的第三方页面列在 `brands[].retrievedSourceIds` 中，而不是作为行动。

### `insights[]`

最多四条简短总结，说明这些页面整体反映了什么：哪些渠道被引用、被引用页面共有的形式、时效性或标准、回答中的品牌顺序
与被引用页面覆盖的内容相比如何，以及你的品牌所处的位置。`sourceIds` 指明每条总结所依据的页面，`linkIds` 指明所依据的关联；
两者至少有一个非空，且只指向本结果中的条目。洞察描述的是对应关系，而不是建议。

## 正确解读结果

* **没有关联不是结论。** 没有关联的段落只是没有匹配到回答范围；没有范围的回答部分只是没有段落与之关联。
  两者都不说明页面无关、未被使用或不可信。
* **未读取的页面仍属未知。** 设置了 `sources[].error` 时，该引用已被排除在分析之外，不要把它缺少关联当作否定结论。
  如果它重要，请重试或提供其 `body`。
* **是对应而非因果。** 结果描述的是已有回答与已有页面文本在事后如何对应，以及这些页面提及了哪些品牌。它不衡量对生成的影响，
  不对页面评分，也不报告回答是如何生成的。
* **`not_found` 表示所有已读取的页面中都没有。** 它不代表你的品牌在网络上不存在。
* **检索数据取决于引擎。** 只有当引擎公开未被引用的页面（ChatGPT、Google AI Overview）或你发送了 `cited: false` 的页面时，
  才会出现未被引用的页面。否则所有来源都是被引用的，你的自有页面也只能以被引用的形式出现。
* **渠道根据主机名判断。** `channel` 是从页面的主机名推断的，而不是通过阅读作者是谁来判断。
* **行动是建议而非保证。** 它们基于本结果中列出的页面排定优先级；执行某项行动并不能确保回答发生变化。
* **id 仅供内部使用。** 不要把 `s…`/`q…`/`b…`/`l…`/`a…` 标识符当作跨运行的稳定键保存；它们只在单个结果内有效。

## 执行与限制

* **规模不会导致失败。** 请求协议接受的一切，即最多 200,000 个字符的 `answer` 与最多 100 条引用，都会被分析。
  长回答、大量来源和超长页面会通过拆分工作来处理，而不是拒绝任务。
* **深度取决于回答，而非页面。** 长页面不会产生比回答所能支撑的更多关联：分析集中在最可能与回答对应的段落，
  并且每个显示出对应关系的来源都会出现在结果中。对于大页面，或在导航、列表和评论中重复同一陈述的页面，
  预期得到的是最有力的段落，而不是每一次出现。
* **标记不是证据。** 站点地图、链接索引和图片库不产生关联；仅由这些构成的页面会以无段落的形式报告，而不是编造对应关系。
* 如果还有其他可读来源，无法读取的来源会在 `sources[].error` 中报告，任务不会失败。当没有任何来源可读、
  分析失败、超时或服务配置错误时，任务失败。
* 请求与 API 其余部分一样按用量计量。提交响应显示临时额度冻结；最终费用在任务进入终止状态时结算。


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