Telegram Username Activity API: пакетная проверка

Пакетная проверка имён пользователей Telegram с возвратом ID пользователя, даты последнего входа, диапазона активных дней и статуса подписки.

Формат входных данных

Загрузите текстовый файл, по одному имени пользователя в строке. Нормализуйте значения перед загрузкой.

@example_user
@another_user

Создание задачи

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

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

API возвращает ID задачи. Сохраните его и используйте для проверки статуса.

Ответ при загрузке

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

Проверка статуса задачи

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

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

Проверяйте статус, пока status не станет exported. Значения pending и processing не означают завершение.

Ответ при обработке

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

Экспортированный ответ

{
  "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"
  }
}

Поля результата

Поле	Описание	Пример
username	Имя пользователя из загруженного файла.	example_user
activated	Зарегистрировано ли имя пользователя в Telegram (yes / no).	yes
uid	Числовой идентификатор пользователя Telegram.	7084480174
lastseen	Дата последнего входа аккаунта (YYYY-MM-DD).	2026-08-01
activedays	Диапазон активных дней по данным поставщика, например over 30 days.	over 30 days
member	Есть ли у аккаунта подписка Telegram (Premium) (yes / no).	no
avatar_url	Ссылка на публичный аватар, размещённый на нашем CDN. Пусто, если у аккаунта нет публичного фото.	https://telegram.waavatar.xyz/v/a.jpg

Примечание: Три продукта по именам пользователей Telegram — это этапы одного конвейера. Аккаунт без публичного аватара останавливается после этапа регистрации, поэтому его столбцы активности и профиля передаются пустыми.

Обработка файла результата

Скачивайте файл по result_url только после экспорта задачи. Сохраняйте имена возвращённых столбцов при дальнейшей обработке.

Поля ответа

Поле	Описание
created_at	Время создания задачи.
updated_at	Время последнего обновления статуса.
task_id	Уникальный идентификатор задачи.
status	pending, processing, exported или failed.
total	Общее число обработанных входных значений.
success	Успешно обработанные значения.
failure	Значения, обработка которых завершилась ошибкой.
result_url	URL для скачивания после экспорта задачи.
actual_amount	Итоговая сумма, если доступна.
estimated_amount	Расчётная сумма, возвращаемая при создании задачи.

Коды состояния

Status	Описание
200	Запрос выполнен успешно.
202	Задача создана успешно, применена предварительная стоимость.
400	Недопустимый файл, неподдерживаемый тип задачи или слишком мало корректных записей.
401	API-ключ отсутствует или недействителен.
402	Недостаточно средств на счёте.
404	Задача не найдена.
413	Загруженный файл слишком велик.
500	Внутренняя ошибка сервера; повторите попытку позже.

Рабочие примечания

• Задача выполняется асинхронно; используйте ID задачи для проверки статуса.
• Перед загрузкой проверьте ограничения продукта на входные данные.
• Ошибочные строки указаны в экспортированном результате и отражены в счётчиках задачи.
• Поля выше основаны на текущем live sample и могут измениться при изменении схемы экспорта.