タスクステータス

GET/v1/tasks/{token}

ステータスが completed または failed になるまでタスクをポーリングしてください。推奨間隔: 3〜5 秒。

ポーリングとダウンロードに使用するトークン。これはタスクエンドポイントの {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	タスク送信時に使用したプロダクトのスラッグ — 一括プロダクト一覧 を参照してください。
country	string | null	タスクの送信時に指定した国。メールプロダクトの場合は null。
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 になったら結果をダウンロードする