Telegram Username Activity Checker API

Check Telegram usernames in bulk and return user ID, last-seen date, active-days band, and membership.

Input format

Upload a text file with one usernames per line. Normalize values before upload; for phone numbers, E.164 format is recommended.

@example_user
@another_user

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=@"./input.txt"' \
--form 'task_type="tg_username_activity"'

The API returns a task ID. Keep this ID and use it to poll the task status.

Upload response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Check 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="d4g8o46p2jvh04o9uolg"'

Poll until status becomes exported. Do not treat pending or processing as a completed result.

Processing response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Exported response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

Result Fields

Field	Description	Example
username	Input username from the submitted file.	example_user
activated	Whether the username is registered on Telegram (yes / no).	yes
uid	Numeric Telegram user ID.	7084480174
lastseen	Date the account was last online (YYYY-MM-DD).	2026-08-01
activedays	Activity band reported upstream, e.g. over 30 days.	over 30 days
member	Whether the account has a Telegram membership (Premium) (yes / no).	no
avatar_url	Public avatar URL, rehosted on our CDN. Empty when the account has no public photo.	https://telegram.waavatar.xyz/v/a.jpg

Note: The three Telegram username products are stages of one pipeline. An account with no public avatar stops after the registration stage, so its activity and profile columns are delivered empty.

Result file handling

Download the file from result_url only after the task is exported. Preserve the returned column names when processing the file downstream.

Response fields

Field	Description
created_at	Timestamp when the task was created.
updated_at	Timestamp of the latest task status update.
task_id	Unique task identifier.
status	pending, processing, exported, or failed.
total	Total input values processed.
success	Values processed successfully.
failure	Values that failed processing.
result_url	Download URL when the task is exported.
actual_amount	Final settled amount, when available.
estimated_amount	Estimated amount returned when the task is created.

Status codes

Status	Description
200	Request successful.
202	Task created successfully and estimated charge applied.
400	Invalid file, unsupported task type, or too few valid entries.
401	Missing or invalid API key.
402	Insufficient account balance.
404	Task not found.
413	Uploaded file is too large.
500	Internal server error; retry later.

Operational notes

• The task is asynchronous; use the task ID for status polling.
• Check product-specific input limits before uploading.
• Failed rows are reported in the exported result and reflected in the task counters.
• The fields above are based on the current live sample and may change when the upstream export schema changes.