Backlinks ID 列表

接口说明

该接口用于获取指定时间范围创建的所有 Backlinks 任务 ID 列表及数据，既已成功完成的任务，也尚未完成的任务。

需要注意：

• 可查询的时间范围最长为调用时间往前 6 个月
• 当任务创建时间在最近 1 个月时，才可返回 metadata
• 单次调用最多返回 1000 个任务 ID
• 调用频率上限为 10 次/分钟

该接口本身不额外收费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准；本接口通常返回 0。

请求地址

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

请求体格式

所有 POST 数据均需使用 UTF-8 编码的 JSON 格式提交，请求体为 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	本次请求总成本，单位 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	获取结果数组

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	该任务成本，单位 USD
metadata	object	任务数据，即创建该任务时提交的参数；在可用且 include_metadata=true 时返回

调用示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/backlinks/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/backlinks/id_list"
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
 }
]
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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

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/backlinks/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.3275 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "backlinks",
 "function": "id_list",
 "datetime_from": "2023-01-11 00:00:00 +02:00",
 "datetime_to": "2023-02-10 18:23:00 +02:00",
 "limit": 100,
 "sort": "desc",
 "include_metadata": true
 },
 "result": [
 {
 "id": "02101804-1535-0265-0000-4f8739f65fcf",
 "url": "v3/backlinks/summary/live",
 "datetime_posted": "2023-02-10 16:04:56 +00:00",
 "datetime_done": "2023-02-10 16:04:56 +00:00",
 "status": "20000",
 "cost": 0.02003,
 "metadata": {
 "api": "backlinks",
 "function": "summary",
 "target": "explodingtopics.com",
 "internal_list_limit": 10,
 "include_subdomains": true,
 "backlinks_filters": [],
 "backlinks_status_type": "all"
 }
 },
 {
 "id": "02081902-1535-0268-0000-32b5cbcfb370",
 "url": "v3/backlinks/domain_intersection/live",
 "datetime_posted": "2023-02-08 17:02:42 +00:00",
 "datetime_done": "2023-02-08 17:02:42 +00:00",
 "status": "20000",
 "cost": 0.0209,
 "metadata": {
 "api": "backlinks",
 "function": "domain_intersection",
 "targets": {
 "1": "youtube.com",
 "2": "homebuilding.co.uk",
 "3": "familyhandyman.com"
 },
 "exclude_targets": [],
 "limit": 30
 }
 }
 ]
 }
 ]
}

状态码说明

• 顶层 status_code 表示本次接口请求的整体执行状态
• tasks[].status_code 表示单个任务的执行状态
• 常见成功状态码为 20000
• 完整错误码与状态信息请参考 /v3/appendix/errors 和 /v3/appendix-errors/

使用注意事项

1. datetime_from 和 datetime_to须按指定时间格式传
2. 若需要返回 metadata，查询窗口不能早于当前时间往前 1 个月
3. 单次最多返回 1000 条记录，如需翻页请合 offset 使用
4. 结果中会已完成与未完成任务，适合做任务审计与批量追踪
5. metadata 在任务仍处于可返回数据的时间范围时可用

实用场景

• 审计任务调用记录：按时间范围拉取 Backlinks 任务 ID，核对团队或系统在某段时间发起了哪些查询
• 追踪未完成任务：筛出尚未完成的任务，便于排查任务积压、时或调度异常
• 回溯历史请求参数：启用 include_metadata 后查看任务创建时的参数，方便复现实验、定位差异
• 构建任务台账：分页获取最近 6 个月的任务列表，沉淀为任务日志与成本追踪数据源
• 分析接口使用结构：根据返回的 url 与 metadata.function 统计常用 Backlinks 功能，优化采集策略与预算分