Skip to main content

Quotas and Usage

GVR tracks request usage per API key through the user account's remainingRequests value.

Single request APIs​

Most API calls consume one request after successful processing.

Examples:

  • voice gender file request
  • voice age request
  • deep voice fake request
  • single name intelligence request

CSV APIs​

CSV processing is different because one file can contain many rows. CSV processing checks the row count and can consume one request per processed row.

If the file has more rows than the key has remaining requests, the API rejects the request before processing the CSV.

Response metadata​

Many successful API responses include updated quota information:

{
  "remainingRequests": 2999
}

Use this value to show usage in your application or to trigger upgrade prompts before a user runs out of quota.

Quota errors​

File and CSV endpoints can return a structured rate-limit response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

Single name endpoints can return:

{
  "error": "Insufficient remaining requests"
}

Practical guidance​

  • Validate required fields before calling the API.
  • Avoid retry loops for validation errors.
  • Treat remainingRequests as the source of truth after each API response.
  • For CSV flows, validate the CSV before starting a large processing job.