Get the status of a batch job
Download OpenAPI spec
GET
/api/v1/verify/batch/{id}
Check the status of a batch job and, once complete, retrieve pre-signed download URLs for the result files. Pre-signed URLs are valid for 7 days from job completion; call this endpoint again to refresh them as long as job data is retained.
Test mode — jobs started with a ev_test_ key complete within seconds and
expose csv_url / json_url just like a live job. The rows carry the canned
per-address outcomes described on POST /api/v1/verify/batch.
Parameters
path · parameters
| Parameter | Type | Description |
|---|---|---|
| id required | string · uuid |
Batch job ID returned by POST /api/v1/verify/batch.
example: 7a4e2c1b-0000-0000-0000-000000000000
|
Responses
200
Job found. Download URLs are included when
status == "complete".
· application/json
401
Missing or invalid API key.
· application/json
403
The API key authenticated but is not scoped for this endpoint (
code: insufficient_scope). It is a 403 rather than a 401 on purpose — the credential is valid, so retrying with it can never help; a key holding the read scope is needed.
· application/json
404
Job not found or belongs to a different key.
· application/json
429
Rate limit exceeded.
· application/json
500
Unexpected server error. The body carries code internal_error plus a request_id to quote in a support request, and never any exception detail.
· application/json
Response schema · 200 · BatchJobResponse
State of a batch job returned by
GET /api/v1/verify/batch/{id}.| Field | Type | Description |
|---|---|---|
| job_id | string · uuid | example: 7a4e2c1b-0000-0000-0000-000000000000 |
| livemode | boolean |
true when the job was submitted with a LIVE key; false when it came from an ev_test_ sandbox key. A key only ever lists — and can only ever fetch — jobs of its own mode.
example: true
|
| status | string |
The job's lifecycle stage. POST /api/v1/verify/batch answers processing at creation — a submission acknowledgement rather than a stage — so treat anything that is not complete or failed as still working, and a stage added later will not break you.
pendingapproval
resolving
smtping
assembling
complete
failed
example: complete
|
| total_rows | integer | Total rows in the uploaded file. example: 1000 |
| billed_rows | integer | Number of rows that were billed. example: 995 |
| original_file_name | string | File name as uploaded. example: emails.csv |
| created_at | string · date-time | example: 2025-06-10T14:00:00Z |
| started_at | string · date-time · null | example: 2025-06-10T14:00:01Z |
| completed_at | string · date-time · null |
UTC timestamp when validation completed. null while processing.
example: 2025-06-10T14:00:45Z
|
| expires_at | string · date-time · null |
UTC timestamp after which result URLs are no longer valid. null while processing.
example: 2025-06-17T14:00:45Z
|
| csv_url | string · null |
Pre-signed download URL for the CSV result file. Valid for 7 days. null while processing.
example: https://storage.example.com/results/job.csv?X-Amz-Expires=604800
|
| json_url | string · null |
Pre-signed download URL for the JSON result file. Valid for 7 days. null while processing.
example: https://storage.example.com/results/job.json?X-Amz-Expires=604800
|
Error responses
401 403 404 429 500 · ApiProblem · object
Standard error response shape used by all error status codes.
| Field | Type | Description |
|---|---|---|
| status required | integer | HTTP status code mirrored in the body. example: 400 |
| code required | string |
Stable, machine-readable error code. Branch your code on this — never on the error text, which is prose and may be reworded at any time.
example: invalid_email
|
| error required | string | Human-readable error message. example: Invalid email format. |
| param | string | The request field the failure is attributable to. Omitted when the failure is not about one specific field. example: email |
| details | array of string · null | Optional per-field validation messages. Null when not applicable. example: ["email: required"] |
| doc_url | string | Link to the documentation for this error code. example: https://emailvalidator.ai/docs/get-started/errors |
| request_id | string | Correlation id for this request. Quote it in a support request — it is how a single call is found in the server logs. example: 0HNCV1TQ3PLRK:00000003 |