# 获取反馈 (/zh/api/analytics/feedback)

<!-- agent-signals: reading_time_min: 4 · est_tokens: 3285 · updated: 2026-07-30 -->
Related: [获取 AI 助手会话记录](/zh/api/analytics/assistant-conversations.md), [获取 AI 助手调用方统计](/zh/api/analytics/assistant-caller-stats.md), [获取页面内容](/zh/api/assistant/get-page-content.md)

<div id="usage">
  ## 用法 [#用法]
</div>

使用此端点导出从文档中收集的用户反馈。反馈包括来自页面评分的上下文反馈、代码片段反馈和 Agent 反馈。

使用响应中返回的 `cursor` 参数对结果进行分页。当 `hasMore` 为 `true` 时继续获取数据。

<div id="filtering">
  ## 筛选 [#筛选]
</div>

可以按以下维度筛选反馈：

* **日期范围**：使用 `dateFrom` 和 `dateTo` 将结果限定在特定时间段内
* **来源**：按 `code_snippet`、`contextual` 或 `agent` 等反馈来源类型进行筛选
* **状态**：按状态值进行筛选，例如 `pending`、`in_progress`、`resolved` 或 `dismissed`

<div id="response-types">
  ## 响应类型 [#响应类型]
</div>

响应会根据不同的 source 包含不同类型的反馈：

* **上下文反馈**：包含 `helpful` 布尔值和可选的 `contact` 邮箱
* **代码片段反馈**：包含 `code`、`filename` 和 `lang` 字段
* **Agent 反馈**：包含 Agent 提交的反馈文本 `comment` 和相关页面的 `path`

<div id="rate-limits">
  ## 速率限制 [#速率限制]
</div>

此端点允许每个组织每小时最多 100 次请求。所有分析端点共享此限制。

`GET /v1/analytics/{projectId}/feedback`

返回按页划分的用户反馈，并支持可选筛选条件

使用管理员 API 密钥进行身份验证。

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string",
        "description": "你的项目 ID，可在控制台的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面中复制。"
      },
      "required": true,
      "name": "projectId",
      "in": "path"
    },
    {
      "schema": {
        "type": "string",
        "description": "ISO 8601 或 YYYY-MM-DD 格式的日期",
        "example": "2024-01-01"
      },
      "required": false,
      "name": "dateFrom",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为不包含在内的上界。结果包括指定日期之前的所有日期，但不包括指定日期当天。",
        "example": "2024-01-01"
      },
      "required": false,
      "name": "dateTo",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "enum": [
          "code_snippet",
          "contextual",
          "agent",
          "thumbs_only"
        ],
        "description": "按反馈来源进行筛选"
      },
      "required": false,
      "name": "source",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "用于筛选的以逗号分隔的状态列表"
      },
      "required": false,
      "name": "status",
      "in": "query"
    },
    {
      "schema": {
        "type": "number",
        "minimum": 1,
        "maximum": 100,
        "default": 50,
        "description": "每页返回的最大结果数"
      },
      "required": false,
      "name": "limit",
      "in": "query"
    },
    {
      "schema": {
        "type": "string",
        "description": "分页游标"
      },
      "required": false,
      "name": "cursor",
      "in": "query"
    }
  ],
  "responses": {
    "200": {
      "description": "包含分页信息的反馈数据",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "feedback": {
                "type": "array",
                "description": "反馈条目的列表。",
                "items": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "反馈的唯一标识符。"
                        },
                        "path": {
                          "type": "string",
                          "description": "源文档的路径或 URL。"
                        },
                        "comment": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "用户提交的反馈内容。"
                        },
                        "createdAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "提交该反馈时的时间戳。"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "code_snippet",
                            "contextual",
                            "agent",
                            "thumbs_only"
                          ],
                          "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈，`agent` 表示由第三方 AI Agent 提交的反馈，`thumbs_only` 表示点赞/点踩投票。"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "in_progress",
                            "resolved",
                            "dismissed"
                          ],
                          "description": "该反馈当前的审核状态。"
                        },
                        "helpful": {
                          "type": "boolean",
                          "description": "用户是否认为该内容有帮助。"
                        },
                        "contact": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "用户提供的用于后续联系的电子邮件地址。"
                        }
                      },
                      "required": [
                        "id",
                        "path",
                        "comment",
                        "createdAt",
                        "source",
                        "status",
                        "helpful",
                        "contact"
                      ],
                      "description": "当来源为 `contextual` 时返回。包含用户是否认为页面有帮助以及可选的联系邮箱。"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "该反馈的唯一标识符。"
                        },
                        "path": {
                          "type": "string",
                          "description": "源文档的路径或 URL。"
                        },
                        "comment": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "用户提交的反馈内容。"
                        },
                        "createdAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "提交该反馈时的时间戳。"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "code_snippet",
                            "contextual",
                            "agent",
                            "thumbs_only"
                          ],
                          "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈，`agent` 表示由第三方 AI Agent 提交的反馈，`thumbs_only` 表示点赞/点踩投票。"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "in_progress",
                            "resolved",
                            "dismissed"
                          ],
                          "description": "反馈当前的审核状态。"
                        },
                        "code": {
                          "type": "string",
                          "description": "与该反馈相关的代码片段。"
                        },
                        "filename": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "与代码片段关联的文件名。"
                        },
                        "lang": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "代码片段所使用的编程语言。"
                        }
                      },
                      "required": [
                        "id",
                        "path",
                        "comment",
                        "createdAt",
                        "source",
                        "status",
                        "code",
                        "filename",
                        "lang"
                      ],
                      "description": "当来源为 `code_snippet` 时返回。包含反馈所涉及代码片段的代码、文件名和编程语言。"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "反馈的唯一标识符。"
                        },
                        "path": {
                          "type": "string",
                          "description": "源文档的路径或 URL。"
                        },
                        "comment": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "用户反馈评论的正文内容。"
                        },
                        "createdAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "提交该反馈时的时间戳。"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "code_snippet",
                            "contextual",
                            "agent",
                            "thumbs_only"
                          ],
                          "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈，`agent` 表示由第三方 AI Agent 提交的反馈，`thumbs_only` 表示点赞/点踩投票。"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "in_progress",
                            "resolved",
                            "dismissed"
                          ],
                          "description": "反馈当前的审核状态。"
                        }
                      },
                      "required": [
                        "id",
                        "path",
                        "comment",
                        "createdAt",
                        "source",
                        "status"
                      ],
                      "description": "当来源为 `agent` 或 `thumbs_only` 时返回。仅包含基本反馈字段。"
                    }
                  ]
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "用于获取下一页结果的游标。如果没有更多结果，则为 null。"
              },
              "hasMore": {
                "type": "boolean",
                "description": "当前页之后是否还有更多结果。"
              }
            },
            "required": [
              "feedback",
              "nextCursor",
              "hasMore"
            ]
          }
        }
      }
    },
    "400": {
      "description": "无效的查询参数",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "描述错误原因的错误信息。"
              },
              "details": {
                "type": "array",
                "description": "关于该错误的其他详细信息。",
                "items": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "对某个特定校验或处理错误的说明。"
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    },
    "500": {
      "description": "服务器错误",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "描述错误原因的错误信息。"
              },
              "details": {
                "type": "array",
                "description": "关于该错误的其他详细信息。",
                "items": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "对某个特定校验或处理错误的说明。"
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
```