---
title: "向 AI 询问您的分析数据"
description: "使用导出分析 API，通过 AI 编码代理以自然语言查询您的 Adapty 分析数据。"
---

用自然语言向 AI 编程助手查询你的 Adapty 数据——收入、转化率、留存率、LTV——让它直接帮你取数。只需将一个能发起 API 调用的工具接入 [Export Analytics API](export-analytics-api)，即可按需查询各项数据图表。
## 可查询的内容 \{#what-you-can-ask-about\}

Export Analytics API 返回的数据与 Adapty 看板数据图表中展示的内容一致。每个数据图表对应一个独立的操作：
| 数据图表 | 涵盖内容 | 操作 |
| --- | --- | --- |
| 收入、MRR、ARR、ARPU | 按时间段、国家或推广活动分组的收入情况 | [retrieveAnalyticsData](https://adapty.io/docs/zh/api-export-analytics/operations/retrieveAnalyticsData.md) |
| 同期群留存 | 某一同期群的订阅用户持续付费的时长 | [retrieveCohortData](https://adapty.io/docs/zh/api-export-analytics/operations/retrieveCohortData.md) |
| 转化率 | 用户从某一步骤或渠道进入下一步骤的比例 | [retrieveConversionData](https://adapty.io/docs/zh/api-export-analytics/operations/retrieveConversionData.md) |
| 流失与漏斗 | 用户在哪些环节流失以及退订速度 | [retrieveFunnelData](https://adapty.io/docs/zh/api-export-analytics/operations/retrieveFunnelData.md) |
| 用户生命周期价值 (LTV) | 各用户市场细分的平均收入随时间的变化 | [retrieveLTVData](https://adapty.io/docs/zh/api-export-analytics/operations/retrieveLTVData.md) |
| 留存率 | 若干天后仍活跃的用户占比 | [retrieveRetentionData](https://adapty.io/docs/zh/api-export-analytics/operations/retrieveRetentionData.md) |
有关参数和筛选条件的完整列表，请参阅 [API 参考](api-export-analytics)。
## 开始之前 \{#before-you-start\}

你需要准备以下三样东西：
- **已有数据的 Adapty 账户**：该 API 返回的数据图表与看板中显示的一致，因此你的应用必须已经在收集分析数据。
- **Secret API 密钥**：在 [App settings → General](https://app.adapty.io/settings/general) 的 **Secret key** 字段中找到。密钥与应用绑定，每个应用需使用独立的密钥。建议将其存储在环境变量中（例如 `ADAPTY_SECRET_KEY`），这样 AI 代理可以直接读取，无需手动粘贴到对话中。
- **能够调用 API 的 AI 工具**：例如 Claude Code、Cursor，或配置了 fetch 工具的 Claude Desktop。claude.ai 或 ChatGPT 等纯对话工具无法直接调用 API。
:::note
export-analytics-secret-key.webp
:::
## 为你的 Agent 提供 API 规范 \{#give-your-agent-the-api-spec\}

[OpenAPI 规范](https://adapty.io/docs/zh/api-specs/export-analytics-api.yaml)描述了每个端点、认证请求头、请求体以及响应示例。Agent 获取规范后，无需你编写任何代码即可构建正确的请求。

通过 URL 向 Agent 提供规范：
- **粘贴 URL**：如果你的 AI 助手支持抓取 URL，将 `https://adapty.io/docs/zh/api-specs/export-analytics-api.yaml` 提供给它，让它读取该规范文件。
- **使用抓取工具**：如果你的 AI 助手有可以获取 URL 的工具（例如 MCP fetch 服务器），将其指向同一 URL 即可。

该规范将 base URL 设置为 `https://api-admin.adapty.io`，因此只要你的密钥已配置到环境中，AI 助手即可获取所有所需信息。
## 查询你的数据 \{#ask-about-your-data\}

加载好规范文件并将密钥设置为环境变量后，就可以用自然语言描述你想查询的数据图表了。

示例提示词：
```
What was my MRR at the end of each month this year, and how does it compare to last year?

Show my trial-to-paid conversion rate for the last 90 days, broken down by product.

Which countries drive the most revenue from my yearly subscription? Top 10.

How is week-1 retention trending for subscribers who started in the last 6 months?

What's the refund rate on my annual plan since launch, by month?

Compare LTV for paid-campaign users vs. organic over the last year, and export it as CSV.
```

智能体将你的请求映射到对应的操作，从环境变量中读取密钥，然后返回数据。默认响应格式为 JSON。如果需要适合电子表格的文件，请指定 CSV 格式——智能体会在请求体中将 `format` 设置为 `csv`。

:::warning
请将密钥保存在环境变量中，不要粘贴到对话框或提交到规则文件中。密钥与应用绑定，如有泄露请在 **Settings → General** 中轮换。详见[轮换 API 密钥](export-analytics-api-authorization#rotate-api-keys)。
:::
## 一次配置，反复使用 \{#set-up-once-for-repeated-use\}

为避免每次会话都重复配置，请将 spec 和 key 保存到 agent 可复用的位置：
- **保存规格链接**：将规格 URL 添加到你的智能体规则或记忆文件中（例如 `CLAUDE.md` 或 Cursor 规则文件），这样每次会话都会自动加载。
- **将密钥存入环境变量**：将 `ADAPTY_SECRET_KEY` 保存到你的 Shell 配置文件或工具的密钥存储中，以后就不需要再手动粘贴了。
- **保存常用提示词或创建自定义技能**：将常用问题保存为提示词，或封装成自定义技能或斜杠命令，让智能体随时按需生成报告。
## 限制 \{#limits\}

请注意以下限制：

- **速率限制**：每个 API 密钥每秒最多允许 2 次请求。超出限制将返回 `429 Too Many Requests` 错误。请告知你的 Agent 在收到 `429` 时等待并重试。
- **应用专属密钥**：每个密钥仅适用于一个应用。如需从多个应用拉取数据，请为每个应用提供对应的密钥。
- **输出格式**：默认响应格式为 JSON。如需导出 CSV，请在请求体中将 `format` 设置为 `csv`。

完整的鉴权和请求规则，请参阅[鉴权与请求格式](export-analytics-api-authorization)。