List batch jobs

GET /api/v1/verify/batch

API key required Base https://api.emailvalidator.ai 60 requests per minute per account

List the batch jobs submitted with this API key's account, newest first. This is how a job is recovered when its job_id was not kept: every other read is by id, and an id you no longer hold cannot be guessed.

Only work submitted through the API is returned — batches started from the web dashboard belong to the dashboard, not to this key.

Download URLs are not included. Each pre-signed URL costs a storage round-trip, so they are produced only for the job you actually want: fetch the job with GET /api/v1/verify/batch/{id} to get csv_url and json_url.

Paging — the response is a cursor-paged list object. Follow next_cursor as starting_after to walk towards older jobs; pass it as ending_before to walk back towards newer ones. has_more tells you whether another page exists in the direction you are walking, and next_cursor is present only when it does. A cursor that will not decode is 400 invalid_request with param naming the parameter it arrived in — answering the first page instead would give the while (has_more) drain loop a fresh cursor forever. Omitting the parameter is still the first page, and a cursor that decodes but points past the end is still an empty page.

Retention — a job's expires_at is when its data is removed, 7 days after submission. After that the job is indistinguishable from one that never existed and GET /api/v1/verify/batch/{id} answers 404.

On this page

Parameters
Responses
Response schema
Error responses
Examples

Parameters

query · parameters

Parameter	Type	Description
limit	integer 1–100 · default 25	Number of jobs to return per page. Values outside 1–100 are clamped. example: 25
starting_after	string	Cursor from a previous response's next_cursor. Returns the page of jobs immediately after it, walking towards older jobs. example: MTc0OTU2NzIwMDAwMDAwMDAwfDdhNGUyLi...
ending_before	string	Cursor from a previous response. Returns the page of jobs immediately before it, walking back towards newer jobs. Ignored when starting_after is also supplied, and — like starting_after — a value that will not decode is rejected with 400 invalid_request rather than silently treated as the first page, even when starting_after would have taken precedence. example: MTc0OTU2NzIwMDAwMDAwMDAwfDdhNGUyLi...
status	string	Return only jobs in this state. Matched case-insensitively; any other value is a 400 rather than a silently unfiltered list. `pendingapproval` `resolving` `smtping` `assembling` `complete` `failed` example: complete

Responses

200

A page of batch jobs, newest first. · application/json

400

The status filter is not one of the documented job states, or a supplied starting_after / ending_before cursor could not be decoded. Both are code: invalid_request with param naming the offending parameter. · 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

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 · BatchJobList

A cursor-paged page of batch jobs, newest first.

Field	Type	Description
object	string	Always `list` — the discriminator that marks a paged collection. `list` example: list
data	array of object	The jobs on this page, ordered newest first.
has_more	boolean	Whether more jobs exist beyond this page in the direction being paged. There is no total count: a cursor walk reveals it, and a per-page count would be stale on arrival. example: true
next_cursor	string	Opaque cursor for the next page, present only when has_more is true. Send it back as starting_after to continue forwards, or as ending_before to continue backwards. example: MTc0OTU2NzIwMDAwMDAwMDAwfDdhNGUyLi...

data · BatchJobListItem · array of object

One batch job in a list page. Identical to BatchJobResponse except that the pre-signed download URLs are omitted — fetch the job by id to get them.

Field	Type	Description
job_id	string · uuid	Unique identifier for the batch job — pass it to `GET /api/v1/verify/batch/{id}`. 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	Current job status. The same value the `status` filter accepts. `pendingapproval` `resolving` `smtping` `assembling` `complete` `failed` example: complete
total_rows	integer	Total rows in the uploaded file. example: 1000
billed_rows	integer · null	Number of rows that were billed. `null` for a job that never started. example: 995
original_file_name	string	File name as uploaded. example: emails.csv
created_at	string · date-time	UTC timestamp when the job was submitted. example: 2025-06-10T14:00:00Z
started_at	string · date-time · null	UTC timestamp when processing began. `null` while the job is unstarted. 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	UTC timestamp when this job's data is removed. After it the job answers 404 rather than a distinguishable expiry error, so read it while the job is still listed. example: 2025-06-17T14:00:45Z

Error responses

400 401 403 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

Example response · 200

{
  "object": "list",
  "data": [
    {
      "job_id": "7a4e2c1b-0000-0000-0000-000000000000",
      "status": "complete",
      "total_rows": 1000,
      "billed_rows": 995,
      "original_file_name": "emails.csv",
      "created_at": "2025-06-10T14:00:00Z",
      "started_at": "2025-06-10T14:00:01Z",
      "completed_at": "2025-06-10T14:00:45Z",
      "expires_at": "2025-06-17T14:00:45Z"
    }
  ],
  "has_more": true,
  "next_cursor": "MTc0OTU2NzIwMDAwMDAwMDAwfDdhNGUyLi..."
}