分析与报告 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

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

日期范围

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

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

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

`truncated` 标志

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

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

消息量摘要

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

GET /analytics/summary

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

cURL

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

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

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()

响应

{
  "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

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

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

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.

响应（第一页）

{
  "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

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

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

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()

响应

{
  "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

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

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

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()

响应

{
  "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

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

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

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()

响应

{
  "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

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

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

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 参考获取完整架构）

{
  "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

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

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

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()

响应

{
  "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

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

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

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()

响应

{
  "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 无法被猜测。

聚合事件计数（旧版）

返回与消息量摘要相同的聚合事件计数，但采用 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

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

响应

{
  "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 端点返回标准的错误封装：

{
  "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 — 已在错误与分页中列出并附有重试指南。

后续步骤

身份验证 — 四种请求身份验证方式。
错误与速率限制 — 状态码及 300 次请求/分钟的限制。
营销活动 API — 可用于筛选这些数据的营销活动。

分析与报告 API #

日期范围 #

truncated 标志 #

消息量摘要 #

额度使用情况 #

AI 成本汇总 #

指标序列 #

对话结果 #

仪表板洞察 #

仪表板 AI 洞察 #

实体活动时间轴 #

聚合事件计数（旧版） #

代理子账户汇总 #

Analytics API 错误 #

后续步骤 #

分析与报告 API

日期范围

`truncated` 标志

消息量摘要

额度使用情况

AI 成本汇总

指标序列

对话结果

仪表板洞察

仪表板 AI 洞察

实体活动时间轴

聚合事件计数（旧版）

代理子账户汇总

Analytics API 错误

后续步骤