content_analysis/id_list

POST /v3/content_analysis/id_list

#分析任务 ID 列表

接口说明

/v3/content_analysis/id_list 用于获取指定时间范围创建的分析任务列表，返回任务 ID 及数据。该接口会同时返回已成功完成和尚未完成的任务。

时间范围限制

• 可查询的任务创建时间范围：最近 6 个月
• 当 include_metadata = true 时：
• datetime_from 最早只能设置为当前时间往前 1 个月
• 且能返回最近 1 个月任务的数据
• datetime_to 最大只能为当前时间

计费与频率限制

• 本接口不收费
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
• 调用频率限制：每分钟最多 10 次
• 单次请求最多返回 1000 个任务 ID

请求信息

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

认证方式

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

请求体格式

所有 POST 数据使用 JSON（UTF-8 编码），请求体为 JSON 数组：

[
 {
 "datetime_from": "2023-01-15 12:57:46 +00:00",
 "datetime_to": "2023-01-31 13:57:46 +00:00",
 "limit": 1000,
 "offset": 0,
 "sort": "asc",
 "include_metadata": false
 }
]

请求参数

字段名	类型	填	说明
datetime_from	string	是	结果筛选的开始时间。为 UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。若 include_metadata=true，最早只能到当前时间前 1 个月；若 include_metadata=false，最早可到当前时间前 6 个月。示例：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
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	URL 路径
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/content_analysis/id_list" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "datetime_from": "2023-01-31 00:00:00 +02:00",
 "datetime_to": "2023-02-01 00:00:00 +02:00",
 "limit": 100,
 "offset": 0,
 "sort": "desc",
 "include_metadata": true
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/content_analysis/id_list"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "datetime_from": "2023-01-31 00:00:00 +02:00",
 "datetime_to": "2023-02-01 00:00:00 +02:00",
 "limit": 100,
 "offset": 0,
 "sort": "desc",
 "include_metadata": True
 }
]

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

if result.get("status_code") == 20000:
 print(result)
else:
 print(f'error. Code: {result.get("status_code")} Message: {result.get("status_message")}')

TypeScript

import axios from "axios";

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

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

响应示例

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.2774 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "content_analysis",
 "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": [
 {
 "internal_list_limit": 8,
 "positive_connotation_threshold": 0.5
 }
 ]
 }
 ]
}

状态码说明

字段	说明
status_code	用于标识请求或任务执行状态
status_message	对应的状态说明文本

常见状态码、错误码及通用信息请参考：

• /v3/appendix/errors
• /v3/appendix-errors/

使用建议

• 若需批量获取任务 ID，建议将 include_metadata 设为 false，可查询最近 6 个月数据
• 若需要回溯任务创建参数，建议将 include_metadata 设为 true，但注意支持最近 1 个月的数据
• 当任务量较大时，合 limit 与 offset 分页拉取
• 建议按 sort=desc 获取最近任务，便于增量同步

实用场景

• 回溯任务执行记录：批量拉取指定时间范围的分析任务 ID，便于审计历史调用与任务产出。
• 同步任务状态：获取已完成与未完成任务列表，建立本地任务台账，提升异步任务跟踪效率。
• 恢复任务上下文：在开启 include_metadata 后取回原始请求参数，便于排查异常结果或复现分析条件。
• 做增量归档：按时间范围和排序规则定期抓取新任务，沉淀分析任务仓库，支持后续报表与复盘。
• 定位异常调用：结合任务状态、完成时间和数据，快速筛查失败任务、重复提交或参数问题。