Get the current credit balance

Download OpenAPI spec

GET /api/v1/credits

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

Return the current credit balance for the authenticated key's account.

On this page

Responses
Response schema
Error responses
Examples

Responses

200

Balance returned. · 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

The account the key was issued for no longer exists. · 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 · CreditsResponse

Current credit balance for the authenticated account.

Field	Type	Description
credits_remaining	integer · null	Sum of `free_credits` and `paid_credits`. `null` for system/demo accounts. example: 4817
free_credits	integer	Complimentary credit balance. example: 317
paid_credits	integer	Purchased credit balance. example: 4500

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	The stable, machine-readable error vocabulary. Every `ApiProblem.code` is one of these values, and this is the WHOLE vocabulary — any one operation emits only the subset its own responses describe. Branch on this and never on the `error` prose, which is human-readable and may be reworded at any time. What each code means, the status it arrives with, and whether retrying can help are documented on the Errors page — the same page every error body links to as its `doc_url`. Three of these are specific to deletion. `result_in_progress` refuses to delete a result that is still being produced. `insufficient_permissions` refuses the ACTOR rather than the key. `result_deleted` is what a charged `Idempotency-Key` answers once the result it named has been deleted. `unauthorized` `invalid_api_key` `insufficient_scope` `insufficient_permissions` `invalid_request` `invalid_email` `invalid_callback_url` `insufficient_credits` `not_found` `job_not_pending` `result_in_progress` `needs_column_selection` `too_many_rows` `unsupported_file_type` `payload_too_large` `rate_limited` `idempotency_in_progress` `idempotency_key_reuse` `idempotency_resource_gone` `result_deleted` `internal_error` 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

{
  "credits_remaining": 4817,
  "free_credits": 317,
  "paid_credits": 4500
}