查询任务进度

GET/v1/tasks/{token}

轮询任务，直到 status 为 completed 或 failed。建议间隔 3-5 秒；5,000 条规模的任务通常会在远不到一分钟内完成。

路径参数是 {token}，取值就是提交时返回的 task_id。

响应示例

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

任务状态说明

status	说明
pending	已入队，等待分配资源。
processing	检测进行中。
completed	已完成，结果可供下载。
failed	执行失败，原因见 failure_message。

响应字段

字段	类型	说明
task_id	string	任务令牌，原样回传。
status	string	pending、processing、completed 或 failed。
progress	integer	完成百分比，0 到 100。
product	string	提交该任务时使用的产品 slug——见批量产品列表。
country	string | null	提交该任务时使用的国家；邮件类产品为 null。
submitted	integer	本次提交收到的行数。
prefiltered	integer	检测前被丢弃的行，例如格式错误的行。
deduped	integer	被去重移除的行数。
total	integer	经预处理与去重后，真正入队检测的行数。
processed	integer	上游通道已处理完成的行数。
valid	integer	确认已注册的行数。
invalid	integer	确认未注册的行数。
unknown	integer	上游无法给出结论的行数。
unknown_processed	integer	已重试并得出结果的 unknown 行。
unknown_unprocessed	integer	仍未解决的 unknown 行，这部分会退款。
stage	string | null	任务运行时的内部阶段名。仅供诊断——不要据此分支逻辑。
stage_seconds	integer | null	在当前阶段已停留的秒数。
last_progress_at	string（ISO 8601）| null	进度最后一次推进的时间。时间戳停止变化意味着任务卡住了，而不只是慢。
failure_message	string | null	任务失败的原因，正常时为 null。
cost_deducted	string	该任务扣除的金额，字符串形式。
cost_refunded	string	对从未完成检测的行退回的金额，字符串形式。
result_available	boolean	为 true 时结果文件可下载。
result_expires_at	string（ISO 8601）| null	结果文件停止可下载的时间。
created_at	string（ISO 8601）	任务创建时间。

如何解读这些计数

submitted 是你提交的数量，total 是实际被检测的数量。只要存在格式错误或重复的行，两者就不相等，差值恰好等于 prefiltered + deduped。

cost_deducted 按 total 计费，cost_refunded 覆盖从未给出结论的行——也就是 unknown_unprocessed 这一桶。只有 valid 与 invalid 两种结论会被计费。

轮询

# Poll until the task leaves pending/processing. `last_progress_at` going
# stale is the real failure signal, not elapsed time.
for i in $(seq 1 120); do
  body=$(curl -s -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
    -H "X-API-Key: YOUR_KEY_HERE")
  status=$(printf '%s' "$body" | jq -r '.status')
  printf '%s %s%%\n' "$status" "$(printf '%s' "$body" | jq -r '.progress')"
  case "$status" in
    completed) printf '%s' "$body" | jq .; break ;;
    failed)    printf '%s' "$body" | jq .; exit 1 ;;
  esac
  sleep 5
done

下一步

• 当 result_available 为 true 后，下载结果