Status da Tarefa

GET/v1/tasks/{token}

Faça polling da tarefa até o status ser completed ou failed. Intervalo recomendado: 3–5 segundos.

Token usado para consultar e baixar. É o parâmetro de caminho {token} dos endpoints de tarefa.

Exemplo de Resposta

{
  "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 da Tarefa

status	Descrição
pending	Na fila, aguardando recursos.
processing	Detecção em andamento.
completed	Concluído. O resultado está pronto para download.
failed	Execução falhou.

Campos da resposta

Campo	Tipo	Descrição
task_id	string	Token usado para consultar e baixar. É o parâmetro de caminho {token} dos endpoints de tarefa.
progress	integer	Percentual concluído, de 0 a 100.
status	string	pending, processing, completed ou failed.
product	string	Slug do produto com que a tarefa foi enviada — veja a lista de produtos em lote.
country	string | null	País com que a tarefa foi enviada, ou null para produtos de e-mail.
submitted	integer	Linhas recebidas no envio.
prefiltered	integer	Linhas descartadas antes da detecção — linhas malformadas, por exemplo.
deduped	integer	Linhas duplicadas removidas.
total	integer	Linhas realmente enfileiradas para detecção, após a pré-filtragem e a deduplicação.
processed	integer	Linhas que o canal upstream concluiu.
valid	integer	Linhas confirmadas como registradas.
invalid	integer	Linhas confirmadas como não registradas.
unknown	integer	Linhas que o provedor não conseguiu resolver.
unknown_processed	integer	Linhas desconhecidas que foram reprocessadas e concluídas.
unknown_unprocessed	integer	Linhas desconhecidas ainda não resolvidas. Estas são reembolsadas.
stage	string | null	Nome interno do estágio enquanto a tarefa está em execução. Apenas para diagnóstico — não ramifique com base nele.
stage_seconds	integer | null	Segundos gastos no estágio atual.
last_progress_at	string (ISO 8601) | null	Quando o progresso avançou pela última vez. Um timestamp que para de avançar significa que a tarefa está travada, e não apenas lenta.
failure_message	string | null	Motivo pelo qual a tarefa falhou, ou null.
cost_deducted	string	Valor deduzido pela tarefa, como string.
cost_refunded	string	Valor reembolsado por linhas que nunca foram verificadas, como string.
result_available	boolean	true quando o arquivo de resultado pode ser baixado.
result_expires_at	string (ISO 8601) | null	Quando o arquivo de resultado deixa de poder ser baixado.
created_at	string (ISO 8601)	Quando a tarefa foi criada.

Como ler as contagens

submitted é o que você enviou; total é o que foi realmente verificado. Eles diferem sempre que houver linhas malformadas ou duplicadas, e a diferença é exatamente prefiltered + deduped.

cost_deducted é cobrado sobre total, e cost_refunded cobre as linhas que nunca foram resolvidas — o grupo unknown_unprocessed. Apenas os veredictos valid e invalid são cobrados.

Consulta periódica

# 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

A seguir

• Baixe os resultados quando result_available for true