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

推送消息链路

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

我的收藏

本页目录：

功能说明

查询指定用户在某个全员推送（App 推送）任务下的推送链路追踪数据。返回该用户所有设备维度的推送全链路状态，包括 IM 提交、厂商通道发送、设备触达、用户点击等各环节的详细信息。

请求 URL 示例

https://xxxxxx/v4/timpush_query/trace?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/trace
请求接口。
usersig
App 管理员账号生成的签名，参见 UserSig 后台 API。
identifier
必须为 App 管理员账号，更多详情请参见 App 管理员。
sdkappid
创建应用时即时通信控制台分配的 SdkAppid。
random
请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype
固定值为：json。

调用频率限制

每秒20次。

请求包示例

{
    "TaskId": "task_001",
    "To_Account": "144115188075855872"
}

请求包字段说明

字段
类型
属性
说明
TaskId
String
必填
推送任务 ID。
To_Account
String
必填
目标用户的账号 ID。不能为空。

应答包体示例

{
    "ActionStatus": "OK",
    "ErrorCode": 0,
    "ErrorInfo": "",
    "InstanceTrace": [
        {
            "PushTime": "2025-03-10 12:00:00",
            "EventType": 1,
            "PushPlatform": 3,
            "DeviceInfo": {
                "InstanceId": "123456789",
                "DeviceModel": "Huawei Mate 60",
                "System": "Android",
                "SystemVersion": "14.0",
                "Token": "AAABBB***",
                "CertId": "12345",
                "SdkVersion": "7.8.5700",
                "PushVersion": "1.0.5",
                "VendorInfo": "Huawei",
                "NotificationStatus": 1,
                "LastActiveTerminal": 1
            },
            "PushStatus": {
                "IMCommitStat": {
                    "IMStat": {
                        "PushStatus": 1,
                        "ErrorCode": 0,
                        "ErrorInfo": "success",
                        "EventTime": "2025-03-10 12:00:01"
                    }
                },
                "OfflinePushStat": {
                    "OfflineStat": {
                        "PushStatus": 1,
                        "ErrorCode": 0,
                        "ErrorInfo": "success",
                        "EventTime": "2025-03-10 12:00:02"
                    },
                    "ChannelStat": {
                        "PushStatus": 1,
                        "ErrorCode": 0,
                        "ErrorInfo": "success",
                        "EventTime": "2025-03-10 12:00:03"
                    },
                    "DeviceStat": {
                        "PushStatus": 1,
                        "ErrorCode": 0,
                        "ErrorInfo": "success",
                        "EventTime": "2025-03-10 12:00:05"
                    },
                    "ClickStat": {
                        "PushStatus": 1,
                        "ErrorCode": 0,
                        "ErrorInfo": "success",
                        "EventTime": "2025-03-10 12:00:10"
                    }
                },
                "VendorPushInfo": {
                    "HuaWei": {
                        "PushID": "hw_push_123",
                        "ChannelID": "channel_001",
                        "Category": "IM"
                    }
                }
            }
        }
    ]
}

应答包字段说明

字段
类型
说明
ActionStatus
String
请求处理的结果：
OK：表示处理成功。
FAIL：表示失败。
ErrorCode
Integer
错误码。0 表示成功，非 0 表示失败。
ErrorInfo
String
错误信息。
InstanceTrace
Array
设备维度的推送追踪结果数组，每个元素对应用户的一台设备。
InstanceTrace 数组中 json Object 字段说明
字段
类型
说明
PushTime
String
推送时间，格式 YYYY-MM-DD HH:mm:ss。
EventType
Integer
推送方式。1：离线推送，2：在线推送。
PushPlatform
Integer
推送平台。1：APNS，2：小米，3：华为，4：FCM，5：魅族，6：OPPO，7：vivo，8：荣耀，9：鸿蒙。
DeviceInfo
Object
设备基础信息。
PushStatus
Object
推送链路各环节状态。
DeviceInfo 字段说明
字段
类型
说明
InstanceId
String
设备实例 ID。
DeviceModel
String
设备型号。
System
String
操作系统（iOS/Android/HarmonyOS）。
SystemVersion
String
系统版本。
Token
String
推送 Token。
CertId
String
推送证书 ID。
SdkVersion
String
IM SDK 版本。
PushVersion
String
推送插件版本。
VendorInfo
String
厂商信息。
NotificationStatus
Integer
通知权限状态。
LastActiveTerminal
Integer
最后活跃终端类型。
Cappid
Integer
子应用 ID（选填，仅多子应用场景返回）。
PushStatus 字段说明
字段
类型
说明
IMCommitStat
Object
IM 提交状态，包含 IMStat 子字段。
OfflinePushStat
Object
离线推送状态，包含 OfflineStat/ChannelStat/DeviceStat/ClickStat 子字段。
OnlinePushStat
Object
在线推送状态，包含 ChannelStat/DeviceStat/ClickStat 子字段。
VendorPushInfo
Object
厂商推送详情，按厂商分组（APNS/XiaoMi/HuaWei/FCM/Meizu/VIVO/OPPO/Honor/Hmony）。
PushStatInfo（各环节状态子字段）字段说明
字段
类型
说明
PushStatus
Integer
推送状态。1：成功，2：失败。
ErrorCode
Integer
错误码。0 表示成功（已通过 codedesc 转换为可读描述）。
ErrorInfo
String
错误描述（已通过 codedesc 转换为可读描述）。
EventTime
String
事件发生时间。

错误码说明

除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码，错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。公共错误码（60000到79999）参见 错误码 文档。
本 API 私有错误码如下：
错误码
含义说明
90100
请求参数无效（JSON 格式错误、TaskId 为空、To_Account 为空等）。
90102
服务内部错误，请稍后重试。

接口调试工具

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

参考

查询全员推送数据统计
查询全员推送折损分析

中国站