Status Tugas

GET/v1/tasks/{token}

Polling tugas hingga status completed atau failed. Interval direkomendasikan: 3–5 detik.

Token yang Anda pakai untuk polling dan mengunduh. Ini adalah parameter path {token} pada endpoint tugas.

Contoh Respons

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

status	Deskripsi
pending	Masuk antrean, menunggu resource.
processing	Pemeriksaan sedang berjalan.
completed	Selesai. Hasil siap diunduh.
failed	Eksekusi gagal.

Bidang Respons

Field	Tipe	Deskripsi
task_id	string	Token yang Anda pakai untuk polling dan mengunduh. Ini adalah parameter path {token} pada endpoint tugas.
progress	integer	Persentase selesai, 0 hingga 100.
status	string	pending, processing, completed atau failed.
product	string	Slug produk yang dipakai saat mengirim tugas — lihat daftar produk massal.
country	string | null	Negara yang dipakai saat tugas dikirim, atau null untuk produk email.
submitted	integer	Baris yang diterima dalam pengiriman.
prefiltered	integer	Baris yang dibuang sebelum deteksi — misalnya baris yang formatnya salah.
deduped	integer	Baris duplikat yang dihapus.
total	integer	Baris yang benar-benar masuk antrean untuk deteksi, setelah penyaringan awal dan penghapusan duplikat.
processed	integer	Baris yang telah diselesaikan oleh kanal hulu.
valid	integer	Baris yang dipastikan terdaftar.
invalid	integer	Baris yang dipastikan tidak terdaftar.
unknown	integer	Baris yang tidak dapat diselesaikan oleh penyedia.
unknown_processed	integer	Baris unknown yang dicoba ulang dan telah selesai.
unknown_unprocessed	integer	Baris unknown yang masih belum terselesaikan. Biaya untuk baris ini dikembalikan.
stage	string | null	Nama tahap internal selama tugas berjalan. Hanya untuk diagnostik — jangan membuat percabangan berdasarkan nilai ini.
stage_seconds	integer | null	Detik yang dihabiskan pada tahap saat ini.
last_progress_at	string (ISO 8601) | null	Kapan progres terakhir kali bergerak maju. Stempel waktu yang berhenti bergerak berarti tugas macet, bukan sekadar lambat.
failure_message	string | null	Alasan tugas gagal, atau null.
cost_deducted	string	Jumlah yang dipotong untuk tugas, sebagai string.
cost_refunded	string	Jumlah yang dikembalikan untuk baris yang tidak pernah diperiksa, sebagai string.
result_available	boolean	true jika file hasil dapat diunduh.
result_expires_at	string (ISO 8601) | null	Kapan file hasil tidak lagi dapat diunduh.
created_at	string (ISO 8601)	Kapan tugas dibuat.

Membaca Jumlah

submitted adalah yang Anda kirim; total adalah yang benar-benar diperiksa. Keduanya berbeda jika ada baris cacat atau duplikat, dan selisihnya tepat prefiltered + deduped.

cost_deducted ditagihkan atas total, dan cost_refunded mencakup baris yang tidak pernah terselesaikan — yaitu kelompok unknown_unprocessed. Hanya putusan valid dan invalid yang ditagih.

Polling

# 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

Berikutnya

• Unduh hasilnya setelah result_available bernilai true