SeerMarTech API 文档

主题

ID 列表 ​

接口说明 ​

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

需要注意：

  • 时间范围最多可追溯到最近 6 个月
  • 当任务创建时间在最近 1 个月时，才可返回 metadata
  • 单次请求最多返回 1000 个任务 ID
  • 调用频率限制为 10 次/分钟

请求地址 ​

POST https://api.seermartech.cn/v3/$path/id_list

动态路径参数 $path 用于指定目标 API 模块，支持以下取值：

  • serp
  • ai_optimization
  • keywords_data
  • domain_analytics
  • dataforseo_labs
  • backlinks
  • on_page
  • content_analysis
  • merchant
  • app_data
  • business_data

计费说明 ​

调用该接口不收费。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式 ​

所有 POST 数据需使用 UTF-8 编码的 JSON 格式提交。 请求体为 JSON 数组：

json
[
 {
 "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
 }
]

请求参数 ​

字段名类型说明
datetime_fromstring结果筛选开始时间，填。若 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_tostring结果筛选结束时间，填。若 include_metadata=true，最早只能查询当前时间往前 1 个月；若 include_metadata=false，最早可查询当前时间往前 6 个月。最大值为当前时间。大于 datetime_from。使用 UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。示例：2023-01-31 13:57:46 +00:00
limitinteger返回任务 ID 的最大数量。可选，默认值 1000，最小值 1，最大值 1000
offsetinteger返回结果中的偏移量。可选，例如设置为 10 时，将跳过前 10 条任务。默认值 0，最小值 0，最大值 100M（1 亿）
sortstring按任务执行时间排序。可选，取值：asc、desc；默认值：asc
include_metadataboolean是否在响应中任务数据。可选，默认值：false。若设为 true，响应中的 metadata 对象将该任务创建时提交的请求参数

响应结构 ​

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger接口通用状态码，错误码参考 /v3/appendix/errors
status_messagestring接口通用状态信息，参考 /v3/appendix/errors
timestring总执行时间，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务数组

tasks 数组字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000，参考 /v3/appendix/errors
status_messagestring任务状态说明，参考 /v3/appendix/errors
timestring任务执行时间，单位秒
costfloat该任务费用，单位 USD
result_countintegerresult 数组中的数量
patharrayURL 路径
dataobject含本次 POST 请求中提交的参数
resultarray获取结果数组

result 数组字段 ​

字段名类型说明
idstring任务 ID
urlstring任务 URL，即调用时所使用的接口路径
datetime_postedstring任务创建时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
datetime_donestring任务完成时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
statusstring任务状态信息，参考 /v3/appendix/errors
costfloat该任务费用，单位 USD
metadataobject任务创建时提交的参数；在 include_metadata=true 且任务在最近 1 个月创建时可返回

调用示例 ​

cURL ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/serp/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 ​

python
import requests

url = "https://api.seermartech.cn/v3/serp/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, headers=headers, json=payload)
data = response.json

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

TypeScript ​

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/serp/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);
 });

响应示例 ​

json
{
 "version": "0.1.20221214",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.6078 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "id_list",
 "datetime_from": "2023-01-07 00:00:00 +02:00",
 "datetime_to": "2023-02-01 00:00:00 +02:00",
 "limit": 100,
 "sort": "desc",
 "include_metadata": true
 },
 "result": [
 {
 "id": "01130021-4426-0139-0000-60d2806c6081",
 "url": "v3/serp/google/dataset_search/live/advanced",
 "datetime_posted": "2023-01-12 22:21:18 +00:00",
 "datetime_done": "2023-01-12 22:21:18 +00:00",
 "status": "20000",
 "cost": 0.020000000000000004,
 "metadata": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "dataset_search",
 "keyword": "water quality",
 "depth": 700,
 "postback_data": "advanced",
 "device": "desktop",
 "os": "windows"
 }
 },
 {
 "id": "01130020-4426-0139-0000-bcded021ab37",
 "url": "v3/serp/google/dataset_search/live/advanced",
 "datetime_posted": "2023-01-12 22:20:17 +00:00",
 "datetime_done": "2023-01-12 22:20:16 +00:00",
 "status": "20000",
 "cost": 0.002,
 "metadata": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "dataset_search",
 "keyword": "water quality",
 "postback_data": "advanced",
 "device": "desktop",
 "os": "windows"
 }
 },
 {
 "id": "01122000-4426-0139-0000-d2a69bec4af8",
 "url": "v3/serp/google/dataset_info/live/advanced",
 "datetime_posted": "2023-01-12 18:00:26 +00:00",
 "datetime_done": "2023-01-12 18:00:25 +00:00",
 "status": "20000",
 "cost": 0.002,
 "metadata": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "dataset_info",
 "dataset_id": "L2cvMTFuMDQ3X3B6aA",
 "postback_data": "advanced",
 "device": "desktop",
 "os": "windows"
 }
 },
 {
 "id": "01121947-4426-0139-0000-8c3f461ee95b",
 "url": "v3/serp/google/dataset_search/live/advanced",
 "datetime_posted": "2023-01-12 17:47:24 +00:00",
 "datetime_done": "2023-01-12 17:47:23 +00:00",
 "status": "20000",
 "cost": 0.002,
 "metadata": {
 "api": "serp",
 "function": "live",
 "se": "google",
 "se_type": "dataset_search",
 "keyword": "water quality",
 "last_updated": "1m",
 "usage_rights": "noncommercial",
 "is_free": true,
 "postback_data": "advanced",
 "device": "desktop",
 "os": "windows"
 }
 }
 ]
 }
 ]
}

状态码与错误 ​

  • 顶层 status_code / status_message 表示整个请求的执行状态
  • tasks[].status_code / tasks[].status_message 表示单个任务的执行状态
  • 通用错误码与状态说明可参考 /v3/appendix/errors

使用说明补 ​

  • 若需要查询历史任务但不心任务提交参数，建议将 include_metadata 设为 false，可将时间范围放宽至最近 6 个月
  • 若需要回溯任务的原始请求参数，则需：
  • 将 include_metadata 设为 true
  • 并确保查询时间范围在最近 1 个月
  • 如果返回任务数量较多，可结合 limit 与 offset 分页获取

实用场景 ​

  • 回溯采集任务：按时间范围拉取已创建任务 ID，快速定位某一批次的 SERP、外链或任务，便于补数和排查
  • 审计任务参数：开启 include_metadata 后查看历史任务提交参数，核对、设备、地区、深度等是否正确
  • 监控任务完成：同时获取已完成与未完成任务，便于建立任务状态巡检机制，及时发现异常批次
  • 构建任务台账：按时间倒序分页拉取任务记录，沉淀任务日志，用于成本分析与操作留痕
  • 下游结果系统：通过任务 ID 和任务 URL 将历史请求与结果存档、报表系统或告警系统进行，提高运营追踪效率

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API