分析与报告 API

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

摘要 — 消息量计数器（已发送、已送达、已读、已回复、已预订、已创建联系人、积分）。
积分 — 包含总计和明细的积分使用详细分页账本。
AI 成本 — AI 支出的每日汇总。
指标序列 — 可用于图表的一个或多个指标的时间序列，按营销活动、渠道、AI 智能体或号码分组。
对话结果 — 随时间变化的对话，按其携带的联系人标签（您的智能体应用的结束标签）分组。
对话成本：AI 独立处理的对话与您的团队介入的对话的平均积分成本对比。
仪表板洞察 和 仪表板 AI 洞察 — 应用内仪表板背后的完整数据，包括 AI 撰写的摘要。
实体活动 — 单个联系人、交易或任务的时间线。
聚合事件计数 — 为现有集成保留的“摘要”的旧版 camelCase 格式。

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

仅有两个端点支持按联系人标签进行筛选。 tag_ids（配合 tag_match 使用）受 Dashboard insights 和 Aggregated event counts 支持——这也是应用内仪表板的 All tags 筛选器所使用的两个端点。Summary、Metric series 和 Conversation outcomes 会验证该参数（格式错误的 ID 列表仍会返回 400），但不会应用它：您将收到整个账户的数据，且不会收到任何错误提示。请勿将未筛选的总数误读为已按标签筛选的数据。

以下所有路径均相对于 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。

额度余额

GET /users/me/credits — 一次调用即可获取您账户当前的额度状况：剩余可用额度、每月配额，以及自动充值和低额度提醒设置。上方的额度使用情况是历史记录；而此处显示的是当前即时余额。团队成员调用此接口需要计费权限；账户所有者的密钥始终拥有该权限。

curl "https://api.youraiconnector.com/v1/users/me/credits?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.youraiconnector.com/v1/users/me/credits", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { balance } = await res.json();

响应 (200)

{
  "success": true,
  "balance": 1837.5,
  "monthly_credits": 2000,
  "used_this_month": null,
  "auto_recharge_enabled": true,
  "low_credit_threshold": null
}

字段	含义
`balance`	剩余可用额度 — 与“额度”卡片上显示的数值相同。
`monthly_credits`	方案的每月配额，若账户无配额则显示 `null`。
`used_this_month`	代理子账户本月已使用的额度；普通账户显示 `null` — 请使用额度使用情况查看相关信息。
`auto_recharge_enabled`	自动充值功能是否开启。
`low_credit_threshold`	触发低额度 Webhook 的余额阈值，若使用默认值则显示 `null`。

代理商可以传入 sub_account_id 来读取客户账户的余额。在自动化流程中，“检查额度”步骤会返回相同的字段。

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 号码桶中。

conversations 计算每个存储桶中开始的对话（聊天会话）数量，conversation_credits 计算这些对话的成本，计算方式与对话成本完全相同。将每个存储桶中的两者相除，即可得出随时间变化的平均每次对话成本。当您按营销活动、代理、渠道或号码进行分组或筛选时，对话将计入其第一条消息所属的类别中。

参数	必需	描述
`from`	否	范围开始，`YYYY-MM-DD`。默认为 30 天前。
`to`	否	范围结束，`YYYY-MM-DD`。默认为今天。
`metrics`	否	来自 `sent`, `ai_sent`, `human_sent`, `automated_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`, `conversations`, `conversation_credits` 的逗号分隔列表。默认为 `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 智能体通过其标签工具、自动标签规则、API 或您的团队所应用的标签。它不是按对话的标签。对话是根据其联系人在请求时携带的标签进行统计的，因此拥有多个标签的联系人会在每个标签下各计一次，而稍后移除的标签也会从过去几天的统计中剔除。为您的智能体针对每个结果提供一个结束标签（例如 resolved_ai, handoff_asked_for_human），此端点即可返回随时间变化的包含情况和转接原因。

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_id": "tag_8f2k1", "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag_id": "tag_c91xq", "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag_id": null, "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}

字段说明：

by_tag[].tag / by_tag[].tag_id — 联系人标签的名称和 ID；在联系人未携带任何标签的对话行中，两者均为 null。最多返回 20 个标签，按数量从高到低排序。
totals.sessions — 在该范围内开始的不同对话。它不是 by_tag[].total 的总和：拥有三个标签的联系人会在三行中各贡献一次对话。
totals.unresolved — 联系人未携带任何标签的对话。
totals.human_alerted — 转接给人工的对话；此项记录在每次转接中，此前未在任何端点中显示。
当报告数据库无法响应时，与指标序列具有相同的 503/analytics_unavailable 状态。

对话成本

返回指定日期范围内对话的平均成本，并按对话情况进行拆分。这是向客户展示投资回报率的数字：AI 独立处理的对话成本，与您的团队必须介入的对话成本对比。

GET /analytics/conversation-costs

参数	必需	描述
`from`	否	开始日期，`YYYY-MM-DD`，包含在内。默认为 30 天前。
`to`	否	结束日期，`YYYY-MM-DD`，包含在内。默认为今天。最大范围为 31 天。
`sub_account_id`	否	代理密钥：报告此客户账户而非您自己的账户。

curl "https://api.youraiconnector.com/v1/analytics/conversation-costs?from=2026-08-26&to=2026-09-24&apiKey=YOUR_API_KEY"

响应

{
  "success": true,
  "from": "2026-08-26",
  "to": "2026-09-24",
  "sessions": 564,
  "total_credits": 5957,
  "summary": {
    "contained": { "sessions": 503, "credits": 5168, "avg_credits": 10.2744 },
    "handed_off": { "sessions": 50, "credits": 781, "avg_credits": 15.62 },
    "no_ai": { "sessions": 11, "credits": 8, "avg_credits": 0.7273 }
  },
  "sessions_truncated": false
}

字段说明：

计算在范围内开始的对话（聊天会话），其中包含在每个对话窗口内扣除的积分，并减去退款。在任何对话之外花费的积分（每日摘要、月费、非由联系人触发的自动化，例如 Webhook 或 RSS 触发器）不包含在内。自 2026 年 9 月 26 日起，由联系人触发的自动化运行和 AI 步骤计入该联系人的对话中。
contained：AI 已回复且您的团队成员无需介入。handed_off：在 AI 回复后有人发送了消息，或者 AI 提醒了人工。no_ai：AI 从未回复（例如您的团队在 AI 暂停时处理的聊天）。
最多计算 20,000 次对话；当范围内的对话超过此数量时，sessions_truncated 为 true，因此请缩小范围。
需要团队成员具备账单权限。与指标序列具有相同的 503/analytics_unavailable 权限要求。
每个联系人的相同拆分可在获取联系人成本中查看。

仪表板洞察

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

GET /analytics/dashboard-insights

参数	必填	描述
`startDate`	是	范围开始，`YYYY-MM-DD`。
`endDate`	是	范围结束，`YYYY-MM-DD`。
`campaignId`	否	仅包含属于此营销活动的活动（也接受 `campaign_id`）。旧版；建议使用 `agent_id`。
`agent_id`	否	仅包含属于此 AI Agent 的活动（也接受 `agentId`）。在 Agent 作用域下，营销活动排行榜仅根据该 Agent 的活动构建。
`tag_ids`	否	以逗号分隔的标签 ID（也接受 `tagIds`，最多 25 个）。将每个数据块缩小到当前带有这些标签中任意一个的联系人——这与“联系人”页面筛选器使用的“匹配任意”规则相同。可与 `campaignId` 或 `agent_id` 结合使用。没有联系人的行（账户级信用充值）将从标签作用域视图中剔除，并且 `conversation_outcomes` 数据块在标签作用域下会返回 `null`。当账户无法使用标签筛选时，返回 `400` 和 `error_code: 400`。
`tag_match`	否	`tag_ids` 如何组合（也接受 `tagMatch`）：`any`（默认——联系人需要具备其中一个标签）或 `all`（联系人需要具备所有标签）。当 `tag_ids` 不存在时被忽略；当 `tag_ids` 存在时，任何其他值都会导致 `400`。
`granularity`	否	仅针对 `metricDailyBreakdown` 的存储桶粒度：`day`（默认）、`week`（基于周一，类似于 `/analytics/series`）或 `month`。其 `labels` 为存储桶的开始时间，且该数据块会带回 `granularity`。其他所有数据块均不受影响。

此端点使用 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 Agent 的事件（也接受 `agentId`）。
`tag_ids`	否	以逗号分隔的标签 ID（也接受 `tagIds`，最多 25 个）。仅统计联系人当前带有这些标签中任意一个的事件。可与 `campaignId` 或 `agent_id` 结合使用。没有联系人的事件（`creditsRecharged`）在标签作用域下会被排除。
`tag_match`	否	`tag_ids` 如何组合（也接受 `tagMatch`）：`any`（默认）或 `all`（仅限具备所有标签的联系人）。当 `tag_ids` 不存在时被忽略；当 `tag_ids` 存在时，任何其他值都会导致 `400`。

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 次请求的限制。
AI 智能体 API — 可用于筛选这些数据的智能体。

分析与报告 API #

日期范围 #

truncated 标志 #

消息量摘要 #

额度使用情况 #

额度余额 #

AI 成本汇总 #

指标序列 #

对话结果 #

对话成本 #

仪表板洞察 #

仪表板 AI 洞察 #

实体活动时间轴 #

聚合事件计数（旧版） #

代理子账户汇总 #

Analytics API 错误 #

后续步骤 #

分析与报告 API

日期范围

`truncated` 标志

消息量摘要

额度使用情况

额度余额

AI 成本汇总

指标序列

对话结果

对话成本

仪表板洞察

仪表板 AI 洞察

实体活动时间轴

聚合事件计数（旧版）

代理子账户汇总

Analytics API 错误

后续步骤