站页面分析任务强制停止

POST /v3/on_page/force_stop

接口说明

该接口用于强制停止您已提交的网站爬取任务。

当您向本接口传一个或多个任务 id 后，这些任务对应的爬取流程会被立即终止。对于停止前已经完成抓取和扫描的页面数据，您仍可继续获取和使用。

• 请求方式：POST
• 接口地址：https://api.seermartech.cn/v3/on_page/force_stop

计费说明

调用本接口本身不收费。

已停止任务的结果数据可在后续 30 天获取。扣费以响应头 X-SeerMarTech-Charge-CNY 为准；本接口通常返回 cost: 0。

请求格式

所有 POST 数据均需使用 JSON（UTF-8 编码）提交。

请求体为 JSON 数组，数组中的每个对象表示一个需要停止的任务。

请求参数

字段名	类型	填	说明
id	string	是	任务 ID。可从 /v3/on_page/task_post/ 的响应中获取。示例：07131248-1535-0216-1000-17384017ad04

使用限制

• 单次请求最多可提交 1000 个 id
• 每个 id 需作为 POST 数组中的一个独立对象传

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/on_page/force_stop" \
 --header "Authorization: Bearer smt_live_YOUR_KEY" \
 --header "Content-Type: application/json" \
 --data-raw '[
 {
 "id": "08121600-1535-0216-0000-37b4c7a34453"
 }
 ]'

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/force_stop"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "id": "08121600-1535-0216-0000-37b4c7a34453"
 }
]

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

TypeScript

import axios from "axios";

const postArray = [
 {
 id: "08121600-1535-0216-0000-37b4c7a34453"
 }
];

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

响应结构

接口返回 JSON 数据，顶层 tasks 数组，用于表示本次提交的各个停止请求结果。

顶层字段说明

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	接口级状态码。完整错误码可参考 /v3/appendix/errors
status_message	string	接口级状态信息
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	任务级状态信息
time	string	单个任务执行耗时，单位为秒
cost	float	单个任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	当前请求的 URL 路径信息
data	object	与请求的数据对象，通常本次操作及原任务的键信息
result	array	结果数组；本接口通常为 null

响应示例

{
 "version": "0.1.20210805",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1008 sec.",
 "cost": 0,
 "tasks_count": 2,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "08121600-1535-0216-0000-37b4c7a34453",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0211 sec.",
 "cost": 0,
 "result_count": 0,
 "path": [
 "v3",
 "on_page",
 "force_stop"
 ],
 "data": {
 "api": "on_page",
 "function": "force_stop",
 "target": "em-autoteile.de",
 "max_crawl_pages": 10,
 "enable_javascript": true,
 "load_resources": true,
 "allow_subdomains": true
 },
 "result": null
 },
 {
 "id": "08121600-1535-0216-0000-d6a5000b6897",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0227 sec.",
 "cost": 0,
 "result_count": 0,
 "path": [
 "v3",
 "on_page",
 "force_stop"
 ],
 "data": {
 "api": "on_page",
 "function": "force_stop",
 "target": "example.com",
 "max_crawl_pages": 10,
 "enable_javascript": true,
 "load_resources": true,
 "allow_subdomains": true
 },
 "result": null
 }
 ]
}

状态码与异常处理

建议您在接时同时处理以下两层状态：

1. 接口级状态：检查顶层 status_code 与 status_message
2. 任务级状态：逐个检查 tasks[] 中每个任务的 status_code 与 status_message

完整错误码与说明请参考：

• /v3/appendix/errors

建议在生产环境中建立完善的异常处理机制，是针对任务不存在、任务已完成、重复停止、参数格式错误等进行底处理。

使用说明补

• 该接口用于停止已创建的站爬取任务
• 停止后，不会删除已抓取完成的页面数据
• 如需获取任务 ID，请调用 /v3/on_page/task_post/
• 如果一个请求中提交多个任务 ID，系统会分别返回每个任务的处理结果

实用场景

• 终止误创建任务：当错误设置了目标站点、抓取深度或子域范围时，立即停止任务，无效抓取占用资源。
• 控制大型站点采集成本：发现电商站、媒体站等页面规模远预期时，及时中断任务，保留已抓取数据并减少后续资源消耗。
• 切换爬取策略：当需要改用不同的 JavaScript、资源加载或页面数限制参数时，停止旧任务，再重新发起更合适的新任务。
• 处理中途异常站点：遇到目标站点响应异常、反爬增强或结构变化时，强制停止任务，持续采集低质量数据。
• 批量回收历史任务：对测试环境或阶段性项目中不再需要继续运行的多个爬取任务进行集中停止，提升任务管理效率。