Keywords Data 任务 ID 列表

接口说明

/v3/keywords_data/id_list 用于获取指定时间范围创建的 Keywords Data 任务 ID 列表及数据，返回结果同时已成功完成和尚未完成的任务。

请注意：

• 可查询的时间范围最长为最近 6 个月
• 当 include_metadata=true 时能获取最近 1 个月任务的数据
• 每次请求最多返回 1000 个任务 ID
• 接口调用频率上限为 10 次/分钟

请求信息

请求方式： POST请求地址： https://api.seermartech.cn/v3/keywords_data/id_list

本接口不单独收费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

POST 请求体需使用 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	结果筛选开始时间。填。当 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	本次请求总费用
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	当前任务费用
result_count	integer	result 数组中的数量
path	array	请求路径
data	object	与请求中提交参数相同的数据对象
result	array	获取结果数组

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	任务状态信息
cost	float	该任务费用
metadata	object	当 include_metadata=true 时返回，创建该任务时提交的参数

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/keywords_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 +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/keywords_data/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/keywords_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.log(error);
});

响应示例

{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3599 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "keywords_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": [
 {
 "id": "02101728-4426-0367-0000-173638950cd5",
 "url": "v3/keywords_data/google_ads/search_volume/live",
 "datetime_posted": "2023-02-10 15:28:26 +00:00",
 "datetime_done": "2023-02-10 15:28:26 +00:00",
 "status": "20000",
 "cost": 0.075,
 "metadata": {
 "api": "keywords_data",
 "function": "search_volume",
 "se": "google_ads",
 "language_code": "en",
 "location_code": 2840,
 "keywords": [],
 "date_from": "2021-08-01"
 }
 }
 ]
 }
 ]
}

状态码与错误说明

• 顶层 status_code / status_message 表示本次接口调用整体执行
• tasks 数组中的 status_code / status_message 表示单个任务的处理结果
• 通用错误码与状态说明请参考：/v3/appendix/errors

使用说明与注意事项

1. datetime_from 与 datetime_to须使用 UTC 时间格式传
2. 若需要返回 metadata，查询时间范围不能早于当前时间前 1 个月
3. 若获取任务 ID 列表而不需要数据，可将 include_metadata 设为 false，此时可查询最近 6 个月的数据
4. 单次最多返回 1000 条记录；如需遍历更多结果，请合 offset 分页获取
5. 返回结果已完成与未完成任务，适合做任务审计、结果补拉和执行追踪

实用场景

• 追踪任务执行状态：批量拉取指定时间段的任务 ID 与状态，快速定位未完成、失败或异常任务，便于补跑与告警。
• 回溯历史采集记录：按时间范围查询最近 6 个月的任务列表，用于审计数据采集覆盖和调用历史。
• 补拉任务结果：通过本接口拿到历史任务 ID，再针对特定任务继续查询或结果，降低漏数风险。
• 分析接口调用成本：结合返回的 cost 与 metadata，统计不同任务类型、搜索引擎或地区的消耗分布。
• 重建业务上下文：开启 include_metadata 后可恢复任务创建时的参数，帮助排查“某次量级/地区/语言设置为何异常”等问题。