跳转到内容

Telegram 用户名活跃检测 API:批量检查

批量检测 Telegram 用户名,并返回用户 ID、最近上线时间、活跃天数与会员状态。

输入格式

每行一个用户名，上传一个文本文件。上传前请先规范化值。

@example_user
@another_user

创建任务

POST https://api.checknumber.ai/v1/tasks

Terminal window
curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="tg_username_activity"'

API 会返回任务 ID。请保存该 ID，并使用它轮询任务状态。

上传响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

检查任务状态

POST https://api.checknumber.ai/v1/gettasks

Terminal window
curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

请持续轮询，直到 status 变为 exported。pending 和 processing 都不表示任务已完成。

处理中的响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

导出响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

结果字段

字段描述示例
username提交文件中的输入用户名。example_user
activated该用户名在 Telegram 上是否已注册(yes / no)。yes
uidTelegram 数字用户 ID。7084480174
lastseen账号最近一次上线日期(YYYY-MM-DD)。2026-08-01
activedays上游给出的活跃天数区间,例如 over 30 days。over 30 days
member账号是否为 Telegram 会员(Premium)(yes / no)。no
avatar_url公开头像地址,已转存至我方 CDN;账号未设公开头像时为空。https://telegram.waavatar.xyz/v/a.jpg

注意:Telegram 用户名三个产品是同一条流水线的三段。没有公开头像的账号在注册段即终结,活跃与画像列以空值交付。

结果文件处理

仅在任务导出后通过 result_url 下载文件。后续处理时请保留返回的列名。

响应字段

字段描述
created_at任务创建时间。
updated_at最近一次任务状态更新时间。
task_id任务唯一标识符。
statuspending、processing、exported 或 failed。
total处理的输入值总数。
success成功处理的值。
failure处理失败的值。
result_url任务导出后的下载地址。
actual_amount最终结算金额（如有）。
estimated_amount创建任务时返回的预估金额。

状态码

Status描述
200请求成功。
202任务创建成功，已应用预估费用。
400文件无效、不支持的任务类型，或有效条目过少。
401API 密钥缺失或无效。
402账户余额不足。
404未找到任务。
413上传文件过大。
500服务器内部错误，请稍后重试。

操作说明

  • 任务为异步处理，请使用任务 ID 轮询状态。
  • 上传前请检查产品专属的输入限制。
  • 失败行会在导出结果中报告，并反映在任务计数器中。
  • 以上字段基于当前线上 sample；上游导出结构变化时，字段也可能变化。