AvatarLookup

Bulk product tg_username_profile_batch

Telegram username profile · Bulk

Upload Telegram usernames and download the profile data, avatar included.

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

View API contractSign 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://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_username_profile_batch \
  -F file=@usernames.txt
Response: task created200 OK
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_profile_batch",
    "status": "processing",
    "total": 1000,
    "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://avatarlookup.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_profile_batch",
    "status": "success",
    "total": 1000,
    "success_cnt": 990,
    "failure_cnt": 10,
    "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.

  1. 01Upload the file

    A .txt or .csv with one phone number per line. It is streamed straight through; nothing is written to disk.

  2. 02Precheck and reserve

    Format and country rules are checked first, then balance is reserved for the valid lines and settled on completion. Nothing is charged if the precheck fails.

  3. 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.

  4. 04Download the result

    Collect the file from the bulk check page. You pay only for phone numbers that actually returned a result; the difference is refunded.

Result fields

Columns in the result file

The download is a zip containing the full result table.

Result file columns

  • username · alexkim
  • activated · yes
  • uid · 123456789
  • lastseen · 2026-09-17 21:40
  • activedays · 12
  • member · no
  • avatar_url · https://example.test/a.jpg

Best for

When to reach for this one

  • Audience review
  • Community analysis
  • Contact data enrichment

Direct answer

What is the bulk Telegram username profile?

Bulk Telegram username profile: submit usernames rather than phone numbers and get the avatar URL, user id, last-online time and active days. There is no country to pick — a username carries no country.

Clear boundaries

What this product does not do

  • Results reflect the moment the task ran. Avatars change — run it again for a fresh state, stored results are never refreshed for you.
  • It is not a reachability or activity check, and not identity verification.
  • Nothing is sent to the identifiers in the file — the lookup reads what each platform publishes.
  • Which columns come back depends on the platform. They are listed on this page before you upload.
  • 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 checkBulk check
How many phone numbers1 phone number per single check; several per multi request — exact caps are in the API docsA whole large list in one task — the current size range is on the pricing page
Getting resultsRight away: single and multi-endpoint answer in the same response; the dashboard returns them one by oneDownload a result file when the task finishes
CountryNone to pick — each number carries its own country code, mix freely in one requestOne country per task, selected at upload and submitted with the file
Result shapeJSON, fields per phone numberResult file (zip with the full table and split lists)
Typical useForm validation, agent lookups, pre-send gatingList hygiene, pre-campaign filtering, stored-data cleanup

Realtime check · View pricing

Product FAQ

About Telegram username profile

When should I use bulk instead of a realtime check?

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

What happens to invalid phone numbers in the file?

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

How long does a task take?

It depends on the phone 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 phone numbers return nothing, that portion is refunded automatically. The difference between the reserved amount and what was actually charged always comes back.

Related products

Other bulk products

ws_profile_batchWhatsApp avatar · BulkUpload a whole file of phone numbers and download the WhatsApp avatar data when the task finishes.tg_profile_batchTelegram profile · BulkUpload phone numbers and download the Telegram profile data, avatar included.viber_profile_batchViber profile · BulkUpload phone numbers and download the Viber profile data, avatar included.max_profile_batchMAX profile · BulkUpload phone numbers and download the MAX profile data, avatar included.line_profile_batchLINE profile · BulkUpload phone numbers and download the LINE profile data, avatar included.zalo_profile_batchZalo profile · BulkUpload phone numbers and download the Zalo profile data, avatar included.email_avatar_batchEmail avatar · BulkUpload a whole file of email addresses and download the avatar data when the task finishes.

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.

Sign Up View pricing