Only the Chinese version of this page is provided currently. The English version will be provided soon.
Help & Documentation>即时通信 IM>推送服务（Push）>服务端 API>定时任务 API>获取定时任务列表

获取定时任务列表

Last updated: 2026-04-07 16:52:37

On this page:

功能说明

本接口用于分页查询定时推送任务列表，支持按创建时间或调度时间排序，支持时间范围过滤和关键词搜索。

接口调用说明

请求 URL 示例

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

调用频率限制

每秒5次。

请求包示例

{
    "Sdkappid": 88888888,
    "Offset": 0,
    "Want": 20,
    "OrderBy": "schedAt",
    "Asc": false,
    "BeginTime": "2025-05-01 00:00:00",
    "EndTime": "2025-06-01 00:00:00",
    "Keyword": "推送标题"
}

请求包字段说明

字段
类型
必填
说明
Sdkappid
Integer
是
应用的 SDKAppID，必须与 URL 中的 sdkappid 一致。
Offset
Integer
是
分页偏移量，从 0 开始。
Want
Integer
是
期望返回的记录数，必须大于 0。
OrderBy
String
是
排序字段：createAt 按创建时间排序，schedAt 按调度时间排序。
Asc
Boolean
是
排序方向，true 为升序，false 为降序。
BeginTime
String
是
查询时间范围的起始时间（UTC），格式 YYYY-MM-DD HH:MM:SS。
EndTime
String
是
查询时间范围的结束时间（UTC），格式 YYYY-MM-DD HH:MM:SS。
Keyword
String
否
搜索关键词，用于模糊匹配任务标题或描述。
注意：
BeginTime 和 EndTime 必须同时设置，且 BeginTime 不能晚于 EndTime。
时间范围不能超过系统配置的最大天数限制。

应答包体示例

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "Total": 2,
    "Tasks": [
        {
            "TaskID": 1234567890,
            "Sdkappid": 88888888,
            "CreateAt": "2025-05-20 08:30:00",
            "Type": "All",
            "SchedAt": "2025-06-01 10:00:00",
            "Content": {
               "From_Account": "administrator",
               "MsgRandom": 985410822,
               "OfflinePushInfo": {
                    "Title": "离线推送标题",
                    "Desc": "离线推送内容"
                }
            },
            "Title": "推送标题1",
            "Desc": "推送描述1",
            "Status": "pending",
            "DispatchSuccess": 0,
            "DispatchErr": "",
            "PushTaskID": ""
        },
        {
            "TaskID": 1234567891,
            "Sdkappid": 88888888,
            "CreateAt": "2025-05-21 09:00:00",
            "Type": "Tag",
            "SchedAt": "2025-06-02 14:00:00",
            "Content": {
                "From_Account": "administrator",
                "MsgRandom": 2114286272,
                "Condition": {
                    "TagsAnd": [
                        "股票A"
                    ]
                },
                "OfflinePushInfo": {
                    "Title": "离线推送标题",
                    "Desc": "离线推送内容"
                }
            },
            "Title": "推送标题2",
            "Desc": "推送描述2",
            "Status": "dispatched",
            "DispatchSuccess": 1,
            "DispatchErr": "",
            "PushTaskID": "69cf7344_537529d8_200003546b784eb_3a080d7b_5152250d"
        }
    ]
}

应答包字段说明

字段
类型
说明
ActionStatus
String
请求处理的结果，OK 表示处理成功，FAIL 表示失败。
ErrorCode
Integer
错误码，0 表示成功，非 0 表示失败。
ErrorInfo
String
错误信息。
Total
Integer
符合条件的任务总数（不受 Offset 和 Want 影响）。
Tasks
Array
定时任务列表，每个元素为一个 TaskInfo 对象。

TaskInfo 字段说明

字段
类型
说明
TaskID
Integer
定时任务 ID。
Sdkappid
Integer
应用的 SDKAppID。
CreateAt
String
任务创建时间（UTC），格式 YYYY-MM-DD HH:MM:SS。
Type
String
推送任务类型：All（全员推送）、Tag（按条件推送）、User（按用户推送）。
SchedAt
String
定时调度时间（UTC），格式 YYYY-MM-DD HH:MM:SS。
Content
Object
推送任务内容。
Title
String
推送标题。
Desc
String
推送描述。
Status
String
任务状态：pending 待执行，dispatching 调度中，dispatched 已调度。
DispatchSuccess
Integer
调度是否成功：0 表示未成功或未调度，1 表示调度成功。
DispatchErr
String
调度失败时的错误信息。
PushTaskID
String
调度成功后生成的推送任务 ID。

错误码说明

除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码，错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。公共错误码（60000到79999）参见 错误码 文档。
本 API 私有错误码如下：
错误码
说明
90104
请求参数无效，例如 Offset 为负数、Want 为0、OrderBy 不合法、时间格式错误、时间范围超限、sdkappid 不匹配等。
90105
内部错误。

中国站 - English