ToAPIsToAPIs
用户文件

查询文件删除进度

查询自有文件删除请求的状态和累计进度

GET
/api/v1/user/file/deletion-requests/{id}

国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.

使用说明

按删除请求 ID 查询当前账号的进度, 他人请求和不存在的请求均返回 404. 计数由后台异步更新, 文件从列表移除后仍保留累计已删除数. processed 表示当前已发现范围处理完成, 迟到登记的旧文件可能使范围和状态再次变化; 不表示所有未登记对象也已清理.

鉴权

Authorizationstring请求头必填

使用系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 API Key, 无需 X-User-Id. 只操作当前认证账号自己的文件和策略, 不合并子账号数据.

请求参数

idstring路径必填

创建删除请求返回的十进制字符串 id, 例如 "456". 这是删除请求 ID, 不是文件 ID.

无查询参数或请求体. 未知或重复查询参数返回 400.

请求示例

curl --request GET \
  --url 'https://api.toapis.com/api/v1/user/file/deletion-requests/456' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/user/file/deletion-requests/456",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.toapis.com/api/v1/user/file/deletion-requests/456", {
  method: "GET",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

响应字段

示例使用虚构数据. 通用响应格式见接入方式.

data.idstring

删除请求 ID, 用于查询进度.

data.scopestring

single 表示删除一个指定文件; all 表示清空当前账号已有文件.

data.file_idstring | null

单文件范围为文件 ID, 批量范围为 null.

data.created_before_atstring | null

批量范围的创建时间截止点, 包含该时刻; 单文件范围为 null.

data.statestring

pending 已受理; running 处理中; processed 当前范围已处理; blocked 有阻塞文件或进度复查失败.

data.discovered_countinteger

当前已发现的范围内文件数, 迟到登记可能使其增加.

data.deleted_countinteger

累计已删除的文件数. 文件从列表移除后, 此计数仍然保留.

data.blocked_countinteger

当前被阻塞的文件数. 进度复查本身失败也可令请求 blocked, 此时计数保留上次成功值.

data.created_atstring

请求创建时间.

data.updated_atstring

进度最近更新时间.

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "id": "456",
    "scope": "single",
    "file_id": "123",
    "created_before_at": null,
    "state": "processed",
    "discovered_count": 1,
    "deleted_count": 1,
    "blocked_count": 0,
    "created_at": "2026-11-16T08:00:00Z",
    "updated_at": "2026-11-16T08:02:00Z"
  }
}

错误处理

请求 ID 或查询参数无效时返回 400. 删除请求不存在或属于其他账号时返回 404; 进度读取暂时不可用时返回 503.

通用鉴权, 限流和错误处理见接入方式.