---
title: 外呼统计接口总览
---

# 外呼统计接口总览

外呼统计接口用于按自定义日期范围查询当前 App Key 绑定空间的**外呼量、接通量、接通率和标签命中通话数**。所有接口均为只读查询，不会产生任何副作用。

## 接口清单

| 接口 | 方法 & 路径 | 最大时间范围 |
| --- | --- | --- |
| [查询外呼量](https://avavox.com/docs/developer/statistics/calls.html) | `GET /open/api/statistics/calls` | 3 个自然月 |
| [查询接通量](https://avavox.com/docs/developer/statistics/connected-calls.html) | `GET /open/api/statistics/connected-calls` | 3 个自然月 |
| [查询接通率](https://avavox.com/docs/developer/statistics/connection-rate.html) | `GET /open/api/statistics/connection-rate` | 3 个自然月 |
| [查询标签命中通话数](https://avavox.com/docs/developer/statistics/tags.html) | `GET /open/api/statistics/tags` | 7 天 |

## 鉴权与数据范围

请求头需携带空间级 App Key：

```shell
Authorization: Bearer <App Key>
```

App Key 的创建与管理详见[《App Key 创建与管理》](https://avavox.com/docs/developer/app-key.html)。

::: warning 仅支持空间级 Key
本组接口只统计 App Key **绑定空间**内的任务外呼数据，不包含呼入、企业其他空间或渠道商下属企业的数据。使用「本企业全部空间」授权范围的企业级 Key 调用会失败。
:::

## 公共请求参数

四个接口均通过 URL 查询参数传入日期范围。

<span style="font-family:monospace; color:#3451b2;">start</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

统计开始日期，格式为 `yyyy-MM-dd`，包含当天。

---

<span style="font-family:monospace; color:#3451b2;">end</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

统计结束日期，格式为 `yyyy-MM-dd`，包含当天。`end` 不能早于 `start`，也不能晚于当前日期。

### 时间范围限制

| 接口 | 单次查询最大范围 |
| --- | --- |
| 外呼量、接通量、接通率 | 3 个自然月，即 `end` 必须早于 `start` 加 3 个月后的日期 |
| 标签命中通话数 | 7 天，即起止日期最多包含 7 个自然日 |

超出限制时请求会失败，请缩短日期范围后重试。

## 统一响应结构

```json
{
  "code": 200,
  "success": true,
  "message": "操作成功",
  "data": {}
}
```

`code` 为 `200` 且 `success` 为 `true` 表示成功。失败时 `success` 为 `false`，`message` 会说明参数、时间范围或授权范围等具体原因。

## 统计口径

- **外呼量**：日期范围内已发起的任务外呼通话总数。
- **接通量**：日期范围内通话时长大于 0 的任务外呼通话数。
- **接通率**：`接通量 ÷ 外呼量 × 100`，返回百分数值并保留两位小数；范围内无外呼时返回 `0.00`。
- **标签命中通话数**：一通电话可分别计入多个标签；同一标签即使在过程标签或结果标签中重复出现，在同一通电话中也只计数一次。

## 相关文档

- [App Key 创建与管理](https://avavox.com/docs/developer/app-key.html)