Job progress and results
Progress counts, and the per-address results when the job has produced any.
Pass include_results=false while polling: dragging a 10,000-row result set through every poll to learn a percentage is expensive for both sides. Results page with limit and next_key.
A job id is matched case-insensitively. Every id is issued lower-case; an upper-cased copy reads the same job (it used to pass the UUID check and then 404).
A cached result row states the cache price once it has been billed at it. The worker copies a cached result's original credits_used: 1. When the job's cache discount has been applied (a batch refunds the difference per cached row only after it reaches completed or cancelled; a single verification settles the same discount), a row with from_cache: true reads credits_used: 0.5. Before that (a job still running, or a finished one whose discount attempt failed and reports cache_discount_pending), or for a legacy verification with no job row to discount it, the row keeps the full credit that is still being held. Reconcile the charge from the job's status, credits_used and credits_refunded; the absence of cache_discount_pending alone does not mean the discount was applied.
Request
- Base URL: https://api.kawaa.com
- URL: https://api.kawaa.com/v1/jobs/{id}
- Auth: one of:
- API key in header X-Api-Key
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://api.kawaa.com/oauth/authorize, token URL https://api.kawaa.com/oauth/token, scopes: verification:read)
Path parameters
The job identifier, a UUID.
Query parameters
false (or 0) leaves the results array out; true (or 1), or leaving the parameter out, includes it. Case-insensitive: FALSE and False are false. Anything else is a 400, including an empty value and no: it is refused before the job is read, rather than guessed at. Until 2026-09-25 only the exact string false turned results off, so 0, no and FALSE silently returned the whole page.
Results per page, 1 to 1000 (default 100). A malformed, fractional, zero, negative or larger value is a 400 rather than clamped, the same rule GET /v1/jobs applies to its own limit. Until 2026-09-25 limit=1001 was silently clamped to 1,000.
The next_key from the previous page. Opaque. It is read only for a batch or file job when results are returned (include_results on and the job has processed rows), and ignored otherwise. A single verification's job (the job_id from POST /v1/verify) has one result and never reads it, so any value there answers 200 with that result. When it is read, a value that does not decode or is not in the shape this endpoint issues is a 400 with code INVALID_CURSOR; start again without it. An empty next_key= is read as no key, the first page.
Response
The job.
Example response
{
"data": {
"results": [
{
"sub_status": "mailbox_exists",
"ai": {
"typo_method": "DirectMapping"
},
"suggestion": "jane@gmail.com"
}
]
}
}Changes
No recorded changes to this operation across all 1 revision of this API.