帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>推送服务（Push）>服务端 API>统计类 API>推送折损分析

推送折损分析

最近更新时间：2026-07-10 16:19:00

我的收藏

本页目录：

功能说明

查询全员推送（App 推送）的折损分析数据，支持按任务 ID 和推送平台过滤，返回发送侧和触达侧的异常错误码分布。查询时间范围最大为最近 7 天。

请求 URL 示例

https://xxxxxx/v4/timpush_query/loss?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json

请求参数说明

参数
说明
https
请求协议：HTTPS。
请求方式：POST。
xxxxxx
SDKAppID 所在国家/地区对应的专属域名。
中国：console.tim.qq.com
新加坡：adminapisgp.im.qcloud.com
首尔：adminapikr.im.qcloud.com
东京：adminapijpn.im.qcloud.com
法兰克福：adminapiger.im.qcloud.com
硅谷：adminapiusa.im.qcloud.com
雅加达：adminapiidn.im.qcloud.com
利雅得：adminapiksa.im.qcloud.com
v4/timpush_query/loss
请求接口。
usersig
App 管理员账号生成的签名，参见 UserSig 后台 API。
identifier
必须为 App 管理员账号，更多详情请参见 App 管理员。
sdkappid
创建应用时即时通信控制台分配的 SdkAppid。
random
请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype
固定值为：json。

调用频率限制

每秒20次。

请求包示例

{
    "StartTime": 1710000000,
    "EndTime": 1710600000,
    "TaskID": ["task_001"],
    "Platform": [1, 3]
}

请求包字段说明

字段
类型
属性
说明
StartTime
Integer
必填
查询起始时间，Unix 时间戳（秒）。与 EndTime 的区间最大为最近 7 天。
EndTime
Integer
必填
查询结束时间，Unix 时间戳（秒）。必须大于 StartTime。
TaskID
Array
选填
推送任务 ID 列表，最多 5 个。不传则查询时间范围内所有任务的汇总折损数据。
Platform
Array
选填
按推送平台过滤。外部枚举值：1=APNS，2=小米，3=华为，4=FCM，5=魅族，6=OPPO，7=vivo，8=荣耀，9=鸿蒙。不传则返回全部平台数据。仅对按平台维度的折损数据（PlatformReadyToSendLoss、PlatformPostSendDeliveredLoss）生效。

应答包体示例

{
    "ActionStatus": "OK",
    "ErrorCode": 0,
    "ErrorInfo": "",
    "Results": [
        {
            "TaskID": "task_001",
            "ReadyToSendLoss": [
                {
                    "ErrCode": "-195",
                    "ErrCount": 120,
                    "ErrInfo": "token is invalid"
                }
            ],
            "PostSendDeliveredLoss": [
                {
                    "ErrCode": "-301",
                    "ErrCount": 50,
                    "ErrInfo": "vendor push failed"
                }
            ],
            "PlatformReadyToSendLoss": [
                {
                    "EventType": 1,
"PushPlatform": 1,
                    "ErrCode": "-195",
                    "ErrCount": 60,
                    "ErrInfo": "token is invalid"
                }
            ],
            "PlatformPostSendDeliveredLoss": [
                {
                    "EventType": 1,
"PushPlatform": 3,
                    "ErrCode": "-301",
                    "ErrCount": 30,
                    "ErrInfo": "vendor push failed"
                }
            ]
        }
    ]
}

应答包字段说明

字段
类型
说明
ActionStatus
String
请求处理的结果：
OK：表示处理成功。
FAIL：表示失败。
ErrorCode
Integer
错误码。0 表示成功，非 0 表示失败。
ErrorInfo
String
错误信息。
Results
Array
折损分析结果数组，每个元素对应一个推送任务的折损数据。
Results 数组中 json Object 字段说明
字段
类型
说明
TaskID
String
推送任务 ID。
ReadyToSendLoss
Array
发送侧折损（汇总），统计从 IM 提交到厂商发送之间的异常。
PostSendDeliveredLoss
Array
触达侧折损（汇总），统计从厂商发送到设备触达之间的异常。
PlatformReadyToSendLoss
Array
发送侧折损（按平台），按推送平台维度的发送侧异常分布。
PlatformPostSendDeliveredLoss
Array
触达侧折损（按平台），按推送平台维度的触达侧异常分布。
折损数组中 json Object（PushLoss）字段说明
字段
类型
说明
EventType
Integer
推送方式。1：离线推送，2：在线推送。仅在按平台维度的折损中返回。
PushPlatform
Integer
推送平台。1：APNS，2：小米，3：华为，4：FCM，5：魅族，6：OPPO，7：vivo，8：荣耀，9：鸿蒙。仅在按平台维度的折损中返回。
ErrCode
String
错误码（已通过 codedesc 转换为可读的错误描述）。
ErrCount
Integer
该错误码出现的次数。
ErrInfo
String
错误描述（已通过 codedesc 转换为可读描述）。

错误码说明

除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码，错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。公共错误码（60000到79999）参见 错误码 文档。
本 API 私有错误码如下：
错误码
含义说明
90100
请求参数无效（JSON 格式错误、StartTime 大于 EndTime、TaskID 超过 5 个、Platform 枚举值不在 1~9 范围等）。
90102
服务内部错误，请稍后重试。

接口调试工具

通过 REST API 在线测试 工具调试本接口。

参考

查询全员推送数据统计
查询全员推送消息链路
中国站