cURL 请求
POST /api/v1/bulk-taskscurl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
-H "X-API-Key: sk_your_api_key" \
-F service_type=tg_username_profile_batch \
-F file=@usernames.txt 在线演示
POST /api/v1/bulk-tasksservice_type=tg_username_profile_batch两步接入：提交文件，再查询任务
提交后立刻返回任务号；之后按任务号查询状态，任务成功时响应里会带上结果文件的下载链接。下面每个请求都配上它自己的响应。
1. 提交文件
立即返回任务号，此时 preparing 为 true，后台正在预处理文件：去掉无效行、重复行，号码任务还会去掉没带国家码和不属于所选国家的号码，这些都不计费。按提交行数冻结余额，完成后按实际用量结算，差额退回。
响应：任务已创建
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "tg_username_profile_batch",
"status": "processing",
"submitted_lines": 1015,
"total": 1015,
"invalid_cnt": 0,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 0,
"preparing": true,
"created_at": "2026-09-08T09:30:00Z"
}
}2. 查询任务
按任务号轮询。预处理完成后恒有 submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt，其中 total 是实际检测并计费的条数。任务成功时响应里带成功/失败计数和结果文件下载链接；预处理阶段被拒的任务为 failed，带 reason_detail，并全额退款。
cURL 请求
GET /api/v1/bulk-tasks/{id}curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"响应：任务已完成
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "tg_username_profile_batch",
"status": "success",
"submitted_lines": 1015,
"total": 1000,
"invalid_cnt": 3,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 12,
"preparing": false,
"success_cnt": 990,
"failure_cnt": 10,
"result_url": "https://…/result.csv",
"created_at": "2026-09-08T09:30:00Z"
}
}一个批量任务是怎么跑完的
批量不是把实时检测放大 —— 它是一次提交、后台执行、稍后取件。整个过程您不需要守着页面，任务状态和结果都留在后台。
01上传号码文件
一行一个号码的 .txt 或 .csv。文件流式提交，服务器不保存文件副本。
02预检并冻结余额
空文件、格式明显不对、行数不足等问题在上传时直接拒绝；通过后冻结余额，文件进入后台预处理：去除重复行和无效行，并校验国家一致性。预处理不通过的任务会标记为失败并全额退款；通过的只检测剩下的条目，完成后结算。
03后台执行
任务在后台跑，您可以关掉页面。失败会立即反馈并全额退款。
04下载结果文件
完成后在批量检测页下载。只按实际返回结果的号码计费，差额自动退回。
结果文件里有哪些列
下载的是一份 CSV 文件，就是这张完整结果表。
结果文件的列
identifier·alex_kim— 提交的用户名，不含 @ 与 t.me/ 前缀（例如 alex_kim）。activated·true— 该用户名是否对应一个存在的 Telegram 账号：true 或 false。不为 true 时，该行其余各列留空。uid·1234567890— Telegram 用户 ID；账号存在时也可能为空。activedays·9— 距上次在线的天数（整数），数值越小越近期。账号隐藏了精确在线时间时，Telegram 只给出大致范围，此时为近似值：0（最近）、7（一周内）、30（一月内）或 1000（很久以前）。账号没有公开任何在线信息时为空。avatar_url·https://cdn5.telesco.pe/file/example.jpg— 头像链接，没有头像时为空。
什么时候该用这一款
用户名名单活跃度分层
activedaysactivated把近期活跃和长期未活跃的用户名分开，优先处理更可能响应的账号。
识别长期不在线的账号
activatedactivedays先确认账号是否存在，再标出长期没有活动迹象的用户名，避免重复投入。
按活跃度分组
activedaysuid按活跃度建立不同分组，辅助后续名单评估与排序。
补全用户 ID 与头像
uidavatar_url把用户 ID 和公开头像链接补回已有用户名名单，减少后续人工查找。
用户名资料检测（批量）是什么？
Telegram 用户名资料检测（批量）在确认账号存在之外，额外返回用户 ID、距上次在线的天数与头像链接。输入是用户名而不是号码；不需要选择国家，每行一个用户名。
这款产品的使用限制
- 不做身份认证。结果只说明这个号码在平台上的注册状态，不能用来确认号码归属人。
- 不返回聊天记录、会话内容或任何私密账号内容。
- 提交任务时选定号码所属的国家/地区。名单应基本属于所选国家；同拨号区的邻国号不算跨国。不符合的名单任务会失败，并全额退款。
- 结果反映任务执行那一刻的状态。需要最新状态就重新跑一次，我方不会自动刷新历史结果。
- 下载链接有时效。任务完成后请尽快下载，过期后可再次查询任务重新获取链接。
什么时候用批量，什么时候实时更合适
| 实时检测 | 批量检测 | |
|---|---|---|
| 号码数量 | 单号 1 个；多号一次可提交多个，具体上限见 API 文档 | 一次跑完整份大名单——当前数量区间见价格页 |
| 拿到结果 | 当场出结果：单号与 API 多号在同一次响应里，网页多号逐个返回 | 任务跑完后下载结果文件 |
| 国家/地区 | 不限，一次可以混着查 | 提交时选定一个国家/地区，名单应基本属于它；混入太多别国号码任务会失败并全额退款 |
| 结果形态 | JSON，逐号字段 | 结果文件（一份 CSV，含完整结果表） |
| 典型用途 | 表单校验、客服复核、发送前实时拦截 | 名单清洗、投放前筛选、存量数据治理 |
关于用户名资料检测的常见问题
什么时候用批量，什么时候用实时检测？
整份大名单用批量。号码不多时用实时检测：同一次请求就出结果，不需要等任务调度。
文件里有无效号码会怎样？
预检阶段会剔除格式不合法的行，它们不计入计费基数。剩下的号码里，上游没能返回结果的那部分也不收费。只对真正拿到结果的号码计价。
任务要跑多久？
取决于号码量与产品类型。提交后可以关掉页面，任务在后台执行，完成后在批量检测页下载结果。
失败了钱会退吗？
会。任务失败全额退款。任务成功但部分号码没出结果，那部分自动退回。提交时冻结的余额与最终实收的差额始终会退。