Telegram Username Avatar Checker API

Retrieve activation status, nickname, and avatar for Telegram usernames. This product accepts usernames directly instead of phone numbers.

Input format

Upload a text file with one Telegram username per line. Accepted formats are username, @username, and t.me/username; full https://t.me/username links are also accepted.

OpenAI
@Telegram
t.me/durov

A valid username is 5–32 characters, starts with a letter, and contains only letters, numbers, or underscores. Results preserve the original spelling, case, and prefix from the uploaded file.

Create a task

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

curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./usernames.txt"' \
--form 'task_type="tg_username_avatar"'

Parameter	Type	Required	Description
`file`	file	Yes	Text file containing one Telegram username per line
`task_type`	string	Yes	Set to `tg_username_avatar`

Successful task creation returns HTTP 202:

{
  "task_id": "d7avatar123example",
  "status": "pending",
  "total": 3,
  "message": "Task created successfully",
  "created_at": "2026-08-11T10:00:00Z"
}

Query task status

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

curl --location 'https://api.numberchecker.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d7avatar123example"'

When status is exported, download the ZIP archive from result_url.

Result files

The ZIP archive contains activated.txt, unregistered.txt, all.csv, and result.xlsx.

all.csv and result.xlsx contain these fields:

Field	Description	Example
`username`	Original username representation from the uploaded file	`t.me/durov`
`activated`	Whether the Telegram username is active	`yes`, `no`
`nickname`	Telegram display name returned for the username	`Pavel Durov`
`avatar`	Avatar URL; empty when unavailable	`https://example.com/avatar.jpg`

The result does not include type or members fields.

Task status response

{
  "created_at": "2026-08-11T10:00:00Z",
  "updated_at": "2026-08-11T10:01:30Z",
  "task_id": "d7avatar123example",
  "user_id": "YOUR_USER_ID",
  "status": "exported",
  "total": 3,
  "success": 3,
  "failure": 0,
  "result_url": "https://example.com/result.zip"
}