Citation Analysis

将一个已完成的 AI 回答与其背后的页面进行比对。结果展示引擎执行的搜索、它检索到的页面和其中被引用的页面、回答提及的品牌以及提及这些品牌的页面、你的品牌所处的位置，以及按优先级排列的行动建议。它还会把每个被引用页面的段落对应到回答中的相应部分，为每条关联附上说明，并总结被引用页面的共同点。这是对已有回答的事后对应分析，不能证明某个来源促使模型生成了某句话，也不是对页面质量的评分。请把它当作需要检查的证据，而不是结论。

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，而不是从结果中复制回答和引用：

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 均可使用。

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 为其自然排名。其他引擎只提供被引用的来源。

请求包含 analysis 时会返回 400。每个结果都包含洞察。

结果

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

{
  "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 其余部分一样按用量计量。提交响应显示临时额度冻结；最终费用在任务进入终止状态时结算。

快速开始

核心概念

回答引擎

搜索与网页数据

请求选项

研究

GEO 监测

账户与数据

分析你已运行过的任务

在采集时分析每一条回答

Payload

结果

`version`

`answer`

`queries[]`

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

`brands[]`

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

`visibility`

`actions[]`

`insights[]`

正确解读结果

执行与限制

​分析你已运行过的任务

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

​Payload

​结果

​version

​answer

​queries[]

​sources[]：每个页面一项

​brands[]

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

​visibility

​actions[]

​insights[]

​正确解读结果

​执行与限制

分析你已运行过的任务

在采集时分析每一条回答

Payload

结果

`version`

`answer`

`queries[]`

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

`brands[]`

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

`visibility`

`actions[]`

`insights[]`

正确解读结果

执行与限制