Business Data 任务 ID 列表

接口说明

该接口用于获取指定时间范围已创建的 Business Data 任务 ID 列表及数据，返回结果同时已成功完成和未完成的任务。

注意事项：

• 可查询的时间范围最长为接口调用时间之前 6 个月
• 当任务创建时间在 最近 1 个月 时，才可返回 metadata
• 本接口本身 不收费
• 调用频率限制：每分钟最多 10 次
• 单次请求最多返回 1000 个任务 ID
• 请求方式为 POST
• 请求体为 JSON 数组：[{ ... }]

接口地址：

POST https://api.seermartech.cn/v3/business_data/id_list

请求参数

字段	类型	说明
datetime_from	string	结果筛选开始时间，填。当 include_metadata=true 时，最早只能查询到当前时间前 1 个月；当 include_metadata=false 时，最早可查询到当前时间前 6 个月。使用 UTC 时间格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2023-01-15 12:57:46 +00:00
datetime_to	string	结果筛选结束时间，填。最大值为当前时间。使用 UTC 时间格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2023-01-31 13:57:46 +00:00
limit	integer	返回的任务 ID 最大数量。可选，默认 1000，最大 1000
offset	integer	返回结果偏移量。可选，默认 0。例如设置为 10 时，将跳过结果中的前 10 条任务
sort	string	按任务执行时间排序。可选，支持值："asc"、"desc"；默认值："asc"
include_metadata	boolean	是否在响应中任务数据。可选，默认 false

响应结构

接口返回 JSON 编码结果，顶层 tasks 数组。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码，完整列表参考 /v3/appendix/errors
status_message	string	通用状态信息，完整列表参考 /v3/appendix/errors
time	string	总执行时间，单位秒
cost	float	本次请求总费用，单位 USD；本接口通常为 0，扣费以响应头 X-SeerMarTech-Charge-CNY 为准
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务数组

tasks[] 字段

字段	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix-errors/
status_message	string	任务状态信息，完整列表参考 /v3/appendix-errors/
time	string	任务执行时间，单位秒
cost	float	任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	含与请求中提交参数相同的数据
result	array	结果数组

tasks[].result[] 字段

字段	类型	说明
id	string	任务 ID
url	string	任务请求 URL，即调用该任务时使用的地址
datetime_posted	string	任务创建时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
datetime_done	string	任务完成时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
status	string	任务状态说明，完整列表参考 /v3/appendix-errors/
cost	float	任务费用，单位 USD
metadata	object	任务数据，创建任务时提交的参数；在 include_metadata=true 且任务满足时间条件时可用

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/business_data/id_list" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "datetime_from": "2023-01-31 00:00:00 +00:00",
 "datetime_to": "2023-02-01 00:00:00 +00:00",
 "limit": 100,
 "offset": 0,
 "sort": "desc",
 "include_metadata": true
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/business_data/id_list"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 "datetime_from": "2023-01-31 00:00:00 +00:00",
 "datetime_to": "2023-02-01 00:00:00 +00:00",
 "limit": 100,
 "offset": 0,
 "sort": "desc",
 "include_metadata": True
 }
]

response = requests.post(url, headers=headers, json=payload)
print(response.json)

TypeScript

import axios from "axios";

const postArray = [
 {
 datetime_from: "2023-01-31 00:00:00 +00:00",
 datetime_to: "2023-02-01 00:00:00 +00:00",
 limit: 100,
 offset: 0,
 sort: "desc",
 include_metadata: true
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/business_data/id_list",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 输出接口返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.4222 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "business_data",
 "function": "id_list",
 "datetime_from": "2023-01-11 00:00:00 +02:00",
 "datetime_to": "2023-02-10 17:47:00 +02:00",
 "limit": 100,
 "sort": "desc",
 "include_metadata": true
 },
 "result": []
 }
 ]
}

状态码与错误说明

• 顶层 status_code 表示整次请求的处理结果
• tasks[].status_code 表示单个任务的处理结果
• 常见成功状态码为 20000
• 任务级状态码范围通常为 10000-60000
• 详细错误码与状态说明可参考：
• /v3/appendix/errors
• /v3/appendix-errors/

使用建议

• 如果只需要任务 ID 列表，建议将 include_metadata 设为 false，可将查询窗口扩展到最近 6 个月
• 如果需要还原任务提交参数，请将 include_metadata 设为 true，但能查询最近 1 个月的任务
• 当返回数量可能较大时，结合 limit 与 offset 分页拉取
• 建议按 datetime_posted 或执行时间维度定期同步，重复扫描大时间范围

实用场景

• 回溯历史任务：按时间范围拉取近 6 个月的任务 ID，便于建立任务台账和执行记录归档
• 排查异常任务：筛选未完成或异常状态任务，快速定位抓取失败、处理中断或参数问题
• 恢复任务上下文：开启 include_metadata 获取任务提交参数，帮助复现历史请求并核查业务
• 构建任务分页同步器：结合 limit 和 offset 批量遍历任务列表，适合做数据仓库增量同步
• 核对费用与执行明细：读取任务级 cost、status、datetime_done 等字段，用于对账和处理时效分析