Public demoPOST /api/v1/bulk-tasksservice_type=tg_username_batch

Bulk product tg_username_batch

Telegram Bulk Username Check

Upload a list of Telegram usernames, confirm which ones belong to real accounts, and get the avatar URL.

An add-on for whole large lists — for a handful of numbers the realtime check answers in the same request. Realtime check →

Usage cost: $0.002 / usernameResponse mode: Asynchronous taskUsernames: 2,000–1,000,000 usernames per taskAPI endpoint: /api/v1/bulk-tasks

View API contract Sign Up

API contract

Two steps: submit the file, then check the task

Read the full API docs Open API Keys

Submitting returns a task id right away; check the task by that id and, once it succeeds, the response carries the result file download link. Each request is shown with its own response.

1. Submit the file

Balance for the valid lines is reserved, to be settled on completion, and the task starts running in the background.

cURL requestPOST /api/v1/bulk-tasks

curl -X POST "https://tgvalidator.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_username_batch \
  -F file=@usernames.txt

Response: task created200 OK

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_batch",
    "status": "processing",
    "total": 2000,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

2. Check the task

Poll by task id. A successful response carries the success and failure counts and the result file download link.

cURL requestGET /api/v1/bulk-tasks/{id}

curl "https://tgvalidator.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response: task finished200 OK

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_batch",
    "status": "success",
    "total": 2000,
    "success_cnt": 1980,
    "failure_cnt": 20,
    "result_url": "https://…/result.zip",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

How it runs

What happens to a bulk task

Bulk is not realtime made bigger — it is submit once, run in the background, collect later. You do not need to keep the page open; task state and results stay in your dashboard.

01Upload the file
A .txt or .csv with one number per line. It is streamed straight through; nothing is written to disk.
02Precheck and reserve
Format and single-country rules are checked first, then balance is reserved for the valid lines and settled on completion. Nothing is charged if the precheck fails.
03Run in the background
The task runs on its own — close the page if you like. A failure is reported straight away and fully refunded.
04Download the result
Collect the file from the bulk check page. You pay only for numbers that actually returned a result; the difference is refunded.

Result fields

Columns in the result file

The download is a zip: alongside this full table it splits registered and unregistered numbers into separate lists.

Result file columns

username · alex_kim — The submitted username (without @).
activated · yes — Whether the username belongs to an existing Telegram account.
avatar_url · <image url> — Public avatar URL, empty when the account has none.

Best for

When to reach for this one

Cleaning username lists
Confirming an account exists
Filling in avatars
Vetting a list before community outreach

Direct answer

What is the bulk Username check?

Telegram bulk username check takes @usernames instead of phone numbers: it confirms whether each username belongs to an existing Telegram account and returns the public avatar URL. No country to choose; one username per line, with or without the @ or t.me/ prefix.

Clear boundaries

What this product does not do

It is not identity verification. A result describes the number's public state on the platform; it cannot confirm who owns the number.
It never returns message history, conversation content, or any private account content.
Choose the country your numbers belong to when submitting. The list should be essentially that one country; neighbours sharing a dialling code do not count as cross-country. Lists that do not qualify are rejected before any charge.
Results reflect the moment the task ran. Run it again for a fresh state — stored results are never refreshed for you.
Download links expire. Fetch the file soon after the task finishes; if a link expires, check the task again for a new one.

When bulk fits

When bulk is worth it — and when realtime is faster

	Realtime check	Bulk check
How many numbers	1 number per single check; several per multi request — exact caps are in the API docs	A whole large list in one task — the current size range is on the pricing page
Getting results	Right away: single and multi-endpoint answer in the same response; the dashboard returns them one by one	Download a result file when the task finishes
Country / region	No restriction — mix freely in one request	Pick one country/region on submission; the list should be essentially that country, and too many numbers from elsewhere are rejected before any charge
Result shape	JSON, fields per number	Result file (zip with the full table and split lists)
Typical use	Form validation, agent lookups, pre-send gating	List hygiene, pre-campaign filtering, stored-data cleanup

Realtime check · View pricing

Product FAQ

About Username check

When should I use bulk instead of a realtime check?

Use bulk for a whole large list. For a handful of numbers the realtime check answers in the same request, with no task to schedule.

What happens to invalid numbers in the file?

The precheck drops malformed lines, so they never enter the billable count. Of the numbers that remain, any the upstream cannot resolve are not charged either. You pay only for numbers that actually return a result.

How long does a task take?

It depends on the number count and the product. You can close the page after submitting; the task runs in the background and the result waits for you on the bulk check page.

Do I get refunded if it fails?

Yes. A failed task is refunded in full. If the task succeeds but some numbers return nothing, that portion is refunded automatically. The difference between the reserved amount and what was actually charged always comes back.

Create an account to submit a bulk task

Bulk and realtime checks draw on the same balance — nothing extra to enable. Sign up and upload your first file on the bulk check page.