Статус задачи

GET/v1/tasks/{token}

Опрашивайте задачу каждые 3–5 секунд до completed или failed.

Токен, с которым вы опрашиваете статус и скачиваете результат. Это параметр пути {token} эндпоинтов задачи.

Пример ответа

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

Статус задачи

status	Описание
pending	В очереди, ожидает ресурсов.
processing	Проверка выполняется.
completed	Завершено. Результат готов к скачиванию.
failed	Выполнение завершилось ошибкой.

Поля ответа

Поле	Тип	Описание
task_id	string	Токен, с которым вы опрашиваете статус и скачиваете результат. Это параметр пути {token} эндпоинтов задачи.
progress	integer	Процент выполнения, от 0 до 100.
status	string	pending, processing, completed или failed.
product	string	Slug продукта, с которым была отправлена задача — смотрите пакетный список продуктов.
country	string | null	Страна, с которой отправлена задача, или null для email-продуктов.
submitted	integer	Строк получено в отправке.
prefiltered	integer	Строки, отброшенные до проверки, — например, некорректные.
deduped	integer	Удалено дублирующихся строк.
total	integer	Строк фактически поставлено на проверку после префильтрации и дедупликации.
processed	integer	Строки, обработанные вышестоящим каналом.
valid	integer	Строки, подтверждённые как зарегистрированные.
invalid	integer	Строки, подтверждённые как незарегистрированные.
unknown	integer	Строки, которые провайдер не смог обработать.
unknown_processed	integer	Неизвестные строки, повторно проверенные и завершённые.
unknown_unprocessed	integer	Неизвестные строки, всё ещё не обработанные. За них возвращаются средства.
stage	string | null	Внутреннее имя этапа, пока задача выполняется. Только для диагностики — не ветвитесь по нему.
stage_seconds	integer | null	Секунд, проведённых на текущем этапе.
last_progress_at	string (ISO 8601) | null	Когда прогресс продвинулся в последний раз. Если отметка времени перестала меняться, задача зависла, а не просто работает медленно.
failure_message	string | null	Причина сбоя задачи или null.
cost_deducted	string	Сумма, списанная за задачу, в виде строки.
cost_refunded	string	Сумма, возвращённая за строки, которые так и не были проверены, в виде строки.
result_available	boolean	true, если файл результата можно скачать.
result_expires_at	string (ISO 8601) | null	Когда файл результата перестаёт скачиваться.
created_at	string (ISO 8601)	Когда задача была создана.

Как читать счётчики

submitted — это то, что вы отправили; total — то, что реально проверено. Они различаются, когда есть некорректные или дублирующиеся строки, и разница ровно равна prefiltered + deduped.

cost_deducted начисляется на total, а cost_refunded покрывает строки, которые так и не получили результата — корзину unknown_unprocessed. Оплачиваются только вердикты valid и invalid.

Опрос

# Poll until the task leaves pending/processing. `last_progress_at` going
# stale is the real failure signal, not elapsed time.
for i in $(seq 1 120); do
  body=$(curl -s -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
    -H "X-API-Key: YOUR_KEY_HERE")
  status=$(printf '%s' "$body" | jq -r '.status')
  printf '%s %s%%\n' "$status" "$(printf '%s' "$body" | jq -r '.progress')"
  case "$status" in
    completed) printf '%s' "$body" | jq .; break ;;
    failed)    printf '%s' "$body" | jq .; exit 1 ;;
  esac
  sleep 5
done

Дальше

• Скачайте результаты, когда result_available станет true