Stop a running batch. Unprocessed addresses are not verified, and the credits held for them are refunded.

The stop is immediate; the refund is not. The job is cancelled the moment this returns, and no message still queued for it will be verified. The refund waits for the addresses already in a worker's hands to finish (the longest an in-flight check can take, plus a margin), because paying back an address that was in fact checked would be wrong in the customer's favour and would leave the job's counters behind its own results. So expect billing_status: "charged" on a cancelled job for a few minutes, then "refunded". Nothing is required of you in between: reading the job, or the platform's own reconciliation sweep, completes it.

charged does not always become refunded. A cancel that arrives just after the last address was checked owes nothing, and the job keeps charged permanently, and correctly, because those credits were spent. Do not wait on the billing status; wait for completed_at. A cancel writes the status immediately and leaves completed_at null, and every path that closes the books (the refund, and the settle for a job that owed nothing) sets it. While it is null a refund is still on its way; once it is set the books are closed however they closed. The counters agree in the ordinary case but not always, and a job the platform reconciled without moving them would keep a counter-based poller waiting for ever.

This is about the money only. The verdicts are final the moment the job reads cancelled: every result is written together with the job's progress counter in one conditional write that requires the job to still be running, so once the cancel lands nothing further can be recorded. Read the results, and the export, straight away. A refund that could not be applied ends at refund_failed, which is also final and needs support rather than patience.

What the job keeps. Every address checked before the cancel stays, and stays billed. GET /v1/jobs/{id} returns those results immediately. GET /v1/jobs/{id}/download exports them without waiting for the refund: the worker writes each result together with the job's progress counter in one conditional write that requires the job to still be running, so the cancel closes the result set as it lands. Index propagation is a separate, much shorter wait: the results index is eventually consistent, so a first download can still answer 409 (retryable: true) or carry complete: false. Retry it. total_emails collapses onto the addresses actually checked and billed, so requested_emails is what you submitted. Read progress as processed_emails of requested_emails.

Repeating the request succeeds. Cancelling an already-cancelled job returns 200 with the job and tries any outstanding refund again; that does not guarantee it lands. completed_at says when it has, and refund_failed is final and needs support. A job that has already completed or failed answers 409: there is nothing left to stop, and its results are unaffected.

Batch and file jobs only. A single verification answers 400: it finishes in seconds and its credit settles when the result lands.

A cancel and a completion cannot both commit: the worker finishes a job on a condition over the running statuses, so whichever of the two writes first makes the other impossible.

{
  "data": {
    "results": [
      {
        "sub_status": "mailbox_exists",
        "ai": {
          "typo_method": "DirectMapping"
        },
        "suggestion": "jane@gmail.com"
      }
    ]
  }
}