Telegram bulk profile check returns the profile fields for each number: user ID, username, first and last name, avatar, estimated age band, gender and ethnicity — and it also carries last-seen time, active days and the member flag, so it is a superset of the activity check. Built for segmenting large lists. The result contains only the profile fields listed above; chat history and message content are never involved.
This is the official TG Validator example repository for one bulk product, tg_profile_batch. It is an asynchronous task: upload a file, get a task id immediately, poll the task, and download the result file when it finishes.
- Product page: https://tgvalidator.com/products/tg_profile_batch
- API documentation: https://tgvalidator.com/api-docs
- API base URL:
https://tgvalidator.com - Authentication:
X-API-Key - Get an API key: https://tgvalidator.com/register
- Audience segmentation
- Targeted list splits
- Avatar asset collection
- First-pass account authenticity
| Column | Example | Meaning |
|---|---|---|
Phone |
+17253100591 |
The submitted number. |
activated |
yes |
Whether the number is registered on Telegram. |
uid |
1234567890 |
Telegram user id. |
username |
alex_kim |
Username, empty when the account has none. |
first_name |
Alex |
Display first name. |
last_name |
Kim |
Display last name. |
Last Online Time |
2026/4/26 17:01 |
The most recent online time observed. |
Active Days |
130 |
Days since that activity. |
Is Member |
No |
Whether the account has Telegram Premium. |
Avatar |
<image url> |
Avatar URL. |
Gender |
male |
Gender estimated from the avatar. |
Age |
25 |
Age band estimated from the avatar. |
Ethnicity |
east_asian |
Ethnicity estimated from the avatar. |
The result is a point-in-time signal, not a verdict, and not identity data. It describes what the provider reported at the moment the task ran.
Upload a .txt or .csv with one phone number per line, 1,000–100,000 valid entries. A number list must come from a single country, given as country — the upstream uses it to expand bare national numbers.
curl -X POST 'https://tgvalidator.com/api/v1/bulk-tasks' \
-H 'X-API-Key: YOUR_API_KEY' \
-F 'product=tg_profile_batch' \
-F 'country=US' \
-F 'file=@numbers.txt'The response returns the task id and status=processing, along with the server-side quote taken before processing starts.
curl -fsS 'https://tgvalidator.com/api/v1/bulk-tasks/TASK_ID' -H 'X-API-Key: YOUR_API_KEY'status is processing, success or failed — there is no progress percentage to poll for. Do not poll more often than once every 30 seconds. When the task succeeds the response carries the result-file download link.
POST /api/v1/bulk-tasks (this repository) takes a file of 1,000–100,000 entries and answers later — that is the shape for list cleaning, campaign preparation and enrichment runs. A realtime check (POST /api/v1/check, or POST /api/v1/batch-check for up to 100 identifiers) answers inside the same HTTP response, for a signup form or a live lookup. The two are separate endpoints and are not interchangeable; see the other repositories under tgvalidator.
The whole file is reserved on submit. When the task finishes you are charged only for the entries that were actually checked and the remainder is returned. A failed task is refunded in full.
| Limit | Value |
|---|---|
| Entries per task | 1,000–100,000 |
| File formats | .txt, .csv, one entry per line |
| Products per task | 1 (tg_profile_batch) |
| Country | required, exactly one per task |
| Poll interval | no more than once per 30 seconds |
40000/40001 are request or file errors; 40100 is an invalid key; 40200 is insufficient balance; 42900 is rate limited — honour Retry-After; 50300 is temporary maintenance. GET /api/v1/balance returns the current balance in data.balance_micros.
Keep the key on a trusted server and read it from TGVALIDATOR_API_KEY. Never commit it or expose it in production browser code.
| Language | Example |
|---|---|
| Python | examples/python |
| Node.js | examples/nodejs |
| Go | examples/go |
| Java | examples/java |
| C# | examples/csharp |
| PHP | examples/php |
| Shell / curl | examples/shell |
- This product: https://tgvalidator.com/products/tg_profile_batch
- All products: https://tgvalidator.com/products
- Documentation: https://tgvalidator.com/api-docs
- Registration: https://tgvalidator.com/register
- Pricing: https://tgvalidator.com/pricing
- OpenAPI contract:
openapi.yaml - License: MIT for the sample code
Submit only data you are authorized to process, and comply with applicable privacy laws and platform terms. Report the signal you received as a signal; do not relabel it downstream as a conclusion it does not support.
Last reviewed: 2026-09-22 · Maintained by TG Validator. Canonical documentation: https://tgvalidator.com/api-docs