Account Balance API

Retrieve credit balance and usage statistics associated with your API key. Returns both account-level data (total remaining credits across all keys) and per-key data (usage for the specific key used in the request) — ideal for building usage dashboards without requiring your users to log in to the StructOCR console.

Endpoint

GEThttps://structocr.com/v1/account/balance

Request Parameters

This is a GET request with no request body. Authentication is via the x-api-key header only.

Parameter	In	Required	Description
x-api-key	Header	Required	Your unique API key. The response reflects balance and usage for the account linked to this key. Manage your keys in the API Management console.

Response Schema

The response contains three top-level objects: period, account, and this_key.

account — Aggregated across all API keys

Field	Type	Description
credits_total	number	Total credits purchased and awarded to the account (all-time).
credits_used	number	Total credits consumed across all API keys (all-time).
credits_remaining	number	Credits available for use (total − used). Use this to determine whether calls can continue.
credits_this_period	number	Credits consumed during the current billing period across all keys.
requests_this_period	number	API calls made during the current billing period across all keys.
error_rate	string	Percentage of requests returning 4xx/5xx this period (e.g. "4.37%").
avg_latency_ms	number	Average response time in milliseconds this period.

this_key — Scoped to the API key used in this request

Field	Type	Description
credits_used	number	Credits consumed by this specific key during the current billing period.
requests	number	API calls made by this specific key during the current billing period.
error_rate	string	Error rate for this specific key this period.
avg_latency_ms	number	Average latency for this specific key this period.

Tip: Issue one API key per downstream user or service to monitor individual consumption via this_key.credits_used.

Code Examples

Request Implementation

curl https://structocr.com/v1/account/balance \
  -H "x-api-key: YOUR_API_KEY"

Success Response (200 OK)

JSON EXAMPLE

{
  "period": {
    "start": "2026-06-01T00:00:00.000Z",
    "end": "2026-06-30T23:59:59.000Z"
  },
  "account": {
    "credits_total": 50569,
    "credits_used": 1720,
    "credits_remaining": 48849,
    "credits_this_period": 337,
    "requests_this_period": 206,
    "error_rate": "4.37%",
    "avg_latency_ms": 2720
  },
  "this_key": {
    "credits_used": 79,
    "requests": 45,
    "error_rate": "2.22%",
    "avg_latency_ms": 2424
  }
}

Error Responses

401 Unauthorized — Missing Header

{
  "error": "Missing x-api-key header"
}

401 Unauthorized — Invalid Key

{
  "error": "Invalid or inactive API key"
}

404 Not Found — Account Missing

{
  "error": "Account not found"
}

500 Internal Server Error

{
  "error": "Failed to fetch usage data"
}

Status Code Definitions

Code	Meaning	Description
200	OK	Request succeeded, balance data returned.
401	UNAUTHORIZED	Missing, invalid, or inactive API key.
404	NOT_FOUND	No account profile linked to this key.
500	INTERNAL_ERROR	Server error while querying data. Retry the request.