# 分析与报告 API

这些只读端点允许您将账户活动提取到您自己的仪表板和报告中：消息事件计数、信用消耗、AI 支出，以及应用内仪表板显示的相同图表和见解。本指南涵盖：

- **摘要** — 消息量计数器（已发送、已送达、已读、已回复、已预约、已创建联系人、信用额度）。
- **信用额度** — 包含总计和明细的详细分页信用使用分类账。
- **AI 成本** — 每日 AI 支出汇总。
- **指标序列** — 一个可用于图表的时间序列，包含一个或多个指标，按活动、渠道、AI 智能体或号码分组。
- **对话结果** — 对话如何结束，按 AI 分配的结果标签分类。
- **仪表板见解** 和 **仪表板 AI 见解** — 应用内仪表板背后的完整数据，包括 AI 撰写的摘要。
- **实体活动** — 单个联系人、交易或任务的时间轴。
- **聚合事件计数** — 摘要的旧版 camelCase 形式，为现有集成保留。

此页面上的每个端点都需要一个确切的作用域，而不是两者都选：在端点接受的情况下，最多传递一个 `campaign_id`（旧版）或 `agent_id`。发送两者将返回 `400`，且如果 ID 不在您的账户中，则返回 `404` 而不是 `403`，因此其他账户的 ID 保持不可猜测。

以下所有路径均相对于 API 基础 URL：

```
https://api.youraiconnector.com/v1
```

每个请求都必须经过身份验证。请参阅 [身份验证](authentication.md) 以了解四种支持的方法。此处的示例使用 `X-API-Key` 标头（以及一种用于 cURL 的查询参数形式）。

---

## 日期范围

所有三个端点都接受相同的可选日期过滤器：

| 参数 | 描述 |
|---|---|
| `from` | 范围的开始，`YYYY-MM-DD`，包含在内。默认为 30 天前。 |
| `to` | 范围的结束，`YYYY-MM-DD`，包含在内。默认为今天。 |

日期按 UTC 时间解释。范围默认为**过去 30 天**，上限为 **366 天** — 更宽的范围将返回 `400`。`from` 不得晚于 `to`。

### `truncated` 标志

**摘要** 和 **额度** 端点限制了单个请求扫描的记录数量。如果您的范围繁忙到达到该上限，响应将包含 `"truncated": true`。当您看到它时，数字基于部分扫描 — 请缩小日期范围（或使用较小的窗口进行分页）以获取完整数据。

::: note
**注意：** 成本和令牌数据仅包含在计入您自己的提供商 API 密钥的 AI 调用中。当您的账户隐藏成本数据时，响应将设置 `"costs_redacted": true`，并且成本字段将返回为零。
:::


---

## 消息量摘要

返回您账户的汇总消息事件计数器，包括范围总计和每日序列。范围内的每一天都会出现在 `by_date` 中 — 无活动的日子将填充为零。可选择使用 `campaign_id` 过滤到单个营销活动。

`GET /analytics/summary`

| 参数 | 必需 | 描述 |
|---|---|---|
| `from` | 否 | 范围起始，`YYYY-MM-DD`。 |
| `to` | 否 | 范围结束，`YYYY-MM-DD`。 |
| `campaign_id` | 否 | 仅统计属于此营销活动的事件。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/summary",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**响应**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total": 1240,
    "sent": 800,
    "delivered": 760,
    "read": 540,
    "replied": 210,
    "booked": 35,
    "contact_created": 120,
    "credits_spent": 412.5,
    "credits_recharged": 500
  },
  "by_date": [
    {
      "date": "2026-05-01",
      "total": 40,
      "sent": 25,
      "delivered": 24,
      "read": 18,
      "replied": 7,
      "booked": 1,
      "contact_created": 4,
      "credits_spent": 13.5,
      "credits_recharged": 0
    }
  ],
  "truncated": false
}
```

`by_date` 中的每个条目都具有与 `totals` 相同的计数器字段，外加一个 `date`。

如果您传递了一个不属于您账户的 `campaign_id`，响应将为 `404` 并附带 `{ "success": false, "error": "Campaign not found" }`。

---

## 额度使用情况

返回指定范围内的额度使用情况：一个分页的个人记录列表，以及范围总计和按原因及营销活动分类的明细。

`GET /analytics/credits`

| 参数 | 必需 | 描述 |
|---|---|---|
| `from` | 否 | 范围起始，`YYYY-MM-DD`。 |
| `to` | 否 | 范围结束，`YYYY-MM-DD`。 |
| `campaign_id` | 否 | 仅包含归因于此营销活动的使用量。 |
| `limit` | 否 | `records` 的页面大小，1–100。默认为 50。 |
| `cursor` | 否 | 传递上一页的 `next_cursor` 以获取下一页。 |

> **调整与消耗的区别：** 余额变动（如奖励、套餐续订和更正）**不包含**在 `totals` 和明细中 —— 它们并非实际消耗。它们仍会出现在 `records` 列表中，并标记为 `"is_adjustment": true`。

**总计和明细仅出现在第一页**（当未提供 `cursor` 时）。在后续页面中，`totals`、`by_reason`、`by_reason_cost` 和 `by_campaign` 将返回为 `null` —— 仅 `records` 数组会继续。这避免了在每一页都重新扫描整个范围。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  limit: "50",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

// To page: pass data.next_cursor as ?cursor on the next request, until it is null.
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/credits",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50},
)
data = res.json()

# To page: pass data["next_cursor"] as cursor on the next request, until it is None.
```

**响应**（第一页）

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "credits_used": 412.5,
    "cost_usd": 1.284512,
    "records": 318
  },
  "by_reason": {
    "AI Message": 380.0,
    "Campaign Message": 32.5
  },
  "by_reason_cost": {
    "AI Message": 1.284512,
    "Campaign Message": 0
  },
  "by_campaign": {
    "Spring Promo": 250.0,
    "Reactivation": 162.5
  },
  "records": [
    {
      "id": "rec_abc123",
      "amount": 1,
      "timestamp": "2026-05-31T14:02:11.000Z",
      "reason": "AI Message",
      "is_adjustment": false,
      "campaign_id": "campaign123",
      "campaign_name": "Spring Promo",
      "contact_id": "contact456",
      "contact_name": "Jane Smith",
      "credit_type": "ai",
      "custom_keys_used": false,
      "description": null,
      "cost_usd": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "ai_model": null,
      "request_id": null,
      "is_test": false
    }
  ],
  "next_cursor": "rec_abc123",
  "costs_redacted": false,
  "truncated": false
}
```

**字段说明：**

- `amount` — 为该记录扣除的额度。对于计费至您自有提供商 API 密钥的记录，此值为零。
- `is_adjustment` — 余额变动的 `true`（不计入总计/明细）。
- `cost_usd`、`input_tokens`、`output_tokens`、`cache_read_tokens`、`cache_creation_tokens`、`ai_model`、`request_id` — 仅在计费至您自有提供商 API 密钥的记录中填充；否则为零或 `null`。
- `is_test` — 游乐场/测试运行的 `true`，这些运行从不计费。
- `next_cursor` — 下一页的游标，当没有更多记录时为 `null`。

---

## AI 成本汇总

返回您账户的每日 AI 支出汇总。此接口读取预聚合的每日总计，因此即使在较长的时间范围内也非常快速。范围内的每一天都会出现在 `days` 中 —— 无活动的日子将填充为零。

`GET /analytics/ai-cost`

| 参数 | 必需 | 描述 |
|---|---|---|
| `from` | 否 | 范围起始，`YYYY-MM-DD`。 |
| `to` | 否 | 范围结束，`YYYY-MM-DD`。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/ai-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**响应**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total_usd": 12.4821,
    "byok_usd": 12.4821,
    "platform_usd": 0,
    "calls": 4210
  },
  "days": [
    {
      "date": "2026-05-01",
      "total_usd": 0.4012,
      "byok_usd": 0.4012,
      "platform_usd": 0,
      "input_usd": 0.18,
      "output_usd": 0.19,
      "cache_creation_usd": 0.02,
      "cache_read_usd": 0.0112,
      "calls": 140,
      "by_provider": { "anthropic": 0.4012 }
    }
  ],
  "costs_redacted": false
}
```

**字段说明：**

- `byok_usd` — 使用您自己的提供商 API 密钥产生的费用。
- `platform_usd` — 在平台上运行而非使用您自己的密钥所产生的费用部分。
- `input_usd`、`output_usd`、`cache_creation_usd`、`cache_read_usd` — 构成 `total_usd` 的成本组成部分。
- `by_provider` — 按 AI 提供商名称分类的美元支出。
- 美元金额仅返回给使用其自身提供商密钥的账户。对于使用额度支付的账户，所有美元字段均为零，且 `costs_redacted` 为 `true`（调用次数仍可见）。

---

## 指标序列

在一次调用中返回一个或多个指标时间序列，可选择按最多两个维度进行分组——这是绑定图表的端点。单个请求可以回答“此活动每天、每个渠道的发送量和回复量”，而无需为每个活动进行一次调用。

`GET /analytics/series`

每个响应都带有一个 `labels` 数组（时间轴，在整个范围内填充零）以及 `series` 中每个组的一个条目，每个条目包含一个针对所请求指标的数组，并与 `labels` 对齐。`limit` 之后的数据序列不会被丢弃——它们会合并到 `other_bucket` 中，计算方式为范围总数减去返回的序列，因此渲染的图表总是加起来等于您的真实数字；当这种情况发生时，`truncated` 为 `true`。

数字的来源：`sent`、`delivered`、`read` 和 `replied` 来自消息记录，其中包含渠道和发送号码。`booked`、`contact_created` 和 `credits_spent` 来自事件流，其中不包含发送号码，因此当您按 `number` 分组时，这些指标会落入 `null` 号码桶中。

| 参数 | 必需 | 描述 |
|---|---|---|
| `from` | 否 | 范围开始，`YYYY-MM-DD`。默认为 30 天前。 |
| `to` | 否 | 范围结束，`YYYY-MM-DD`。默认为今天。 |
| `metrics` | 否 | 来自 `sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent` 的逗号分隔列表。默认为 `sent,replied`。未知的指标返回 `400`。 |
| `group_by` | 否 | 最多两个维度的逗号分隔列表，来自 `date`, `campaign`, `channel`, `agent`, `number`。`date` 被接受但无效——每个响应已经携带了时间轴。省略则获取整个账户的单个序列。 |
| `granularity` | 否 | `day`（默认）、`week` 或 `month`。周桶从周一开始，月桶从 1 号开始。 |
| `limit` | 否 | 在其余部分合并到 `other_bucket` 之前返回多少个序列，1–50。默认为 12。 |
| `campaign_id` | 否 | 仅计算属于此活动的活动。旧版；建议使用 `agent_id`。 |
| `agent_id` | 否 | 仅计算属于此 AI 智能体的活动。 |
| `channel` | 否 | 仅计算此渠道上的活动，例如 `whatsapp`。 |

此端点的日期范围上限为 **92 天**（比此页面其他地方使用的 366 天上限更严格）。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  metrics: "sent,replied,booked",
  group_by: "campaign,channel",
  limit: "10",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/series",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "from": "2026-05-01",
        "to": "2026-05-31",
        "metrics": "sent,replied,booked",
        "group_by": "campaign,channel",
        "limit": 10,
    },
)
data = res.json()
```

**响应**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "granularity": "day",
  "labels": ["2026-05-01", "2026-05-02"],
  "group_by": ["campaign", "channel"],
  "metrics": ["sent", "replied", "booked"],
  "series": [
    {
      "key": {
        "campaign_id": "campaign123",
        "campaign_name": "Spring Promo",
        "channel": "whatsapp"
      },
      "total": 812,
      "metrics": {
        "sent": [40, 35],
        "replied": [12, 9],
        "booked": [2, 1]
      }
    }
  ],
  "other_bucket": {
    "series_count": 6,
    "total": 340,
    "metrics": {
      "sent": [18, 20],
      "replied": [5, 6],
      "booked": [0, 1]
    }
  },
  "truncated": true
}
```

**字段说明：**

- `key` — 一个序列的标识。仅存在所请求 `group_by` 维度的键；对于某一行值未知的维度（没有活动的活动，没有渠道的事件），返回 `null` 而不是被丢弃，因此序列仍然加起来等于总数。
- `other_bucket` — 当没有内容被合并时为 `null`。
- 当报告数据库无法为您的账户提供答案时，此端点返回带有 `"error_code": "analytics_unavailable"` 的 `503`，而不是充满零的 `200` —— 归零的图表会被误读为事实。

---

## 对话结果

返回日期范围内对话的结束方式：AI 分配的每个结果标签的每日计数，以及回复、预约、移交给人工和 AI 从未分类的对话的范围总计。

`GET /analytics/outcomes`

传递 `group_by=tag` 以折叠时间轴并仅获取每个标签的范围总计——在该模式下 `labels` 为空，每个标签的 `counts` 数组也为空，而 `total` 仍然被填充。

| 参数 | 必填 | 说明 |
|---|---|---|
| `from` | 否 | 范围开始，`YYYY-MM-DD`。默认为 30 天前。 |
| `to` | 否 | 范围结束，`YYYY-MM-DD`。默认为今天。 |
| `campaign_id` | 否 | 仅统计当前处于此营销活动中的联系人的对话。旧版；建议使用 `agent_id`。 |
| `agent_id` | 否 | 仅统计属于此 AI 智能体的结果。 |
| `group_by` | 否 | `date`（默认）保留每日计数；`tag` 将其折叠为范围总计。 |

此端点的日期范围上限为 **92 天**。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/outcomes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**响应**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "group_by": "date",
  "labels": ["2026-05-01", "2026-05-02"],
  "by_tag": [
    { "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}
```

**字段说明：**

- `by_tag[].tag` — AI 未分配结果标签的对话的 `null`。
- `totals.human_alerted` — 转交给人工的对话；此项会记录在每次转交中，且此前未在任何端点中显示。
- 当报告数据库无法响应时，与指标系列具有相同的 `503`/`analytics_unavailable` 状态。

---

## 仪表板洞察

一次调用即可返回日期范围内的完整仪表板有效负载：按工作日和小时划分的回复率热图、营销活动排行榜、各渠道流量、精确的各连接总数、每日指标细分（账户级、各渠道和各号码）、联系人来源、收件箱响应时间以及近期活动摘要。这是 API 上最丰富的报告有效负载 — 它直接为应用内仪表板提供支持。

`GET /analytics/dashboard-insights`

| 参数 | 必填 | 说明 |
|---|---|---|
| `startDate` | 是 | 范围开始，`YYYY-MM-DD`。 |
| `endDate` | 是 | 范围结束，`YYYY-MM-DD`。 |
| `campaignId` | 否 | 仅包含属于此营销活动的活动（也接受 `campaign_id`）。旧版；建议使用 `agent_id`。 |
| `agent_id` | 否 | 仅包含属于此 AI 智能体的活动（也接受 `agentId`）。在智能体范围内，营销活动排行榜仅根据该智能体的活动构建。 |

此端点使用 `startDate`/`endDate`（而非 `from`/`to`），因为它与应用内仪表板共享实现。范围上限为 92 天，当范围超出时会被**截断，而不是拒绝**。

> **Null 表示不可用，而非零。** 几个区块（`numberStats`、`channelDailySeries`、`metricDailyBreakdown`、`contactsByCountry`）是从报告数据库计算得出的，当数据库无法为您的账户提供答案时，它们会返回 `null`。请勿将 `null` 区块渲染为空图表。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()
```

**响应**（已删减 — 此有效负载很大；请参阅 [API 参考](reference.md) 获取完整架构）

```json
{
  "success": true,
  "data": {
    "heatmap": {
      "buckets": [
        { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 }
      ]
    },
    "topCampaigns": [
      { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 }
    ],
    "channelVolume": [
      { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" }
    ],
    "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 },
    "activityFeed": [
      { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" }
    ],
    "numberStats": null,
    "channelDailySeries": null,
    "metricDailyBreakdown": null,
    "contactsByCountry": null,
    "ai_human_split": null
  }
}
```

**字段说明：**

- `heatmap.buckets[].weekday` — `0` 为周日，`6` 为周六。
- `numberStats`、`channelDailySeries`、`metricDailyBreakdown`、`contactsByCountry`、`ai_human_split` — 当报告数据库对您的账户不可用时，每个区块都会独立返回 `null`；其他所有区块仍会正常返回。

---

## 仪表板 AI 洞察

返回三条由 AI 编写的关于账户在日期范围内消息传递的简短洞察：一个成功案例、一个值得关注的事项和一个建议 — 这些句子您可以直接粘贴到报告中，而无需自己解读数字。仅根据账户自身的消息指标生成。

`GET /analytics/dashboard-ai-insights`

| 参数 | 必填 | 说明 |
|---|---|---|
| `startDate` | 是 | 范围开始，`YYYY-MM-DD`。 |
| `endDate` | 是 | 范围结束，`YYYY-MM-DD`。 |

此端点是账户级别的 — 它不接受任何营销活动或代理范围。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()
```

**响应**

```json
{
  "success": true,
  "data": {
    "insights": [
      { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." },
      { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." },
      { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." }
    ]
  }
}
```

缺少 `startDate` 或 `endDate` 将返回 `400`。

---

## 实体活动时间轴

以时间轴形式返回单个联系人、交易或任务的活动，按时间从新到旧排序：包含在消息、预约、备注和状态变更中发生了什么以及发生的时间。使用此端点可以回答“此人发生了什么”，而无需拼接多个列表端点。

`GET /analytics/entity-activity`

| 参数 | 必需 | 描述 |
|---|---|---|
| `entityType` | 是 | `contact`、`deal` 或 `task`。 |
| `entityId` | 是 | 要返回其时间轴的记录 ID。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/entity-activity",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"entityType": "contact", "entityId": "contact456"},
)
data = res.json()
```

**响应**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "evt_9",
        "kind": "appointment_booked",
        "at": "2026-05-31T14:02:11.000Z",
        "label": "Booked an appointment for June 3",
        "detail": "Consultation call, 30 minutes"
      },
      {
        "id": "evt_8",
        "kind": "message_replied",
        "at": "2026-05-31T13:58:02.000Z",
        "label": "Replied: \"Yes, that time works\""
      }
    ]
  }
}
```

缺少或无效的 `entityType`/`entityId` 将返回 `400`。如果实体在您的账户中不存在，则返回 `404`，因此其他账户的 ID 无法被猜测。

---

## 聚合事件计数（旧版）

返回与 [消息量摘要](#message-volume-summary) 相同的聚合事件计数，但采用 camelCase 格式（`contactCreated` 而非 `contact_created`，`byDate` 而非 `by_date`），这是某些旧版集成所使用的格式。新集成请优先使用 `/analytics/summary` — 此端点仅为了让应用内仪表板和 API 共享同一实现而存在。

`GET /analytics/aggregate`

| 参数 | 必需 | 描述 |
|---|---|---|
| `startDate` | 否 | 范围开始时间，ISO 日期或日期时间格式。默认为 `/analytics/summary` 使用的相同窗口。 |
| `endDate` | 否 | 范围结束时间，ISO 日期或日期时间格式。 |
| `campaignId` | 否 | 仅统计属于此营销活动的事件（也接受 `campaign_id`）。旧版；请优先使用 `agent_id`。 |
| `agent_id` | 否 | 仅统计属于此 AI 代理的事件（也接受 `agentId`）。 |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**响应**

```json
{
  "success": true,
  "data": {
    "from": "2026-05-01",
    "to": "2026-05-31",
    "total": 1240,
    "byAnalyticType": {
      "total": 1240,
      "sent": 800,
      "delivered": 760,
      "read": 540,
      "replied": 210,
      "booked": 35,
      "contactCreated": 120,
      "creditsSpent": 412.5,
      "creditsRecharged": 500
    },
    "byDate": [
      { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } }
    ]
  }
}
```

---

## 代理子账户汇总


---

## Analytics API 错误

Analytics 端点返回标准的错误封装：

```json
{
  "success": false,
  "error": "Date range too large. Maximum is 366 days."
}
```

在分析端点上，无效的日期格式或超出范围的窗口将返回 `400`，未知的 `campaign_id` 或 `agent_id` 将返回 `404`。在同时接受 `campaign_id` 和 `agent_id` 的端点上发送两者也是 `400` — 最多只能传递一个。仅限 PG 的报告端点（指标序列、对话结果、代理汇总）在报告数据库无法为您的账户提供答案时，会返回 `503` 和 `"error_code": "analytics_unavailable"`，而不是返回充满零的 `200` — 请稍后重试。每个端点都可能返回的共享代码 — `401`、`403`（您的套餐不包含 API 访问权限，或者在代理汇总中，您的账户不是代理/开发角色）、`429`（速率限制）和 `500` — 已在 [错误与分页](errors-and-pagination.md) 中列出并附有重试指南。

---

## 后续步骤

- [身份验证](authentication.md) — 四种请求身份验证方式。
- [错误与速率限制](errors-and-pagination.md) — 状态码及 300 次请求/分钟的限制。
- [营销活动 API](campaigns.md) — 可用于筛选这些数据的营销活动。