Get credit balance
GET /api/credits/balance
Retrieve the authenticated user's current credit balance
Authentication
- Option 1:
x-api-key: YOUR_API_KEY(header). API key for authentication. Create one in your dashboard. - Option 2:
Authorization: Bearer YOUR_ACCESS_TOKEN. Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.
Create API keys at app.zvid.io/api-keys. Keep credentials on your server.
Parameters
This operation has no path, query, or additional header parameters.
Request
The shell examples read credentials from ZVID_API_KEY (or ZVID_ACCESS_TOKEN for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.
This operation does not take a request body.
Request example
curl --request GET 'https://api.zvid.io/api/credits/balance' \
--header "x-api-key: $ZVID_API_KEY"
Responses
HTTP 200
Credit balance retrieved successfully
Content type: application/json.
Unknown properties are rejected. Required properties: balance, subscriptionCredits, addonCredits.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.balance | integer | Yes | Total available credits from subscription and add-on pools |
response.subscriptionCredits | integer | Yes | Credits remaining in the current subscription period |
response.addonCredits | object | Yes | Add-on credit pool and historical add-on totals Unknown properties are rejected. Required properties: balance, totalEarned, totalSpent. |
Nested field: response.addonCredits
Add-on credit pool and historical add-on totals
Unknown properties are rejected. Required properties: balance, totalEarned, totalSpent.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.addonCredits.balance | integer | Yes | Available add-on credits |
response.addonCredits.totalEarned | integer | Yes | Total add-on credits earned over all time |
response.addonCredits.totalSpent | integer | Yes | Total add-on credits spent over all time |
Example response
{
"balance": 1800,
"subscriptionCredits": 1200,
"addonCredits": {
"balance": 600,
"totalEarned": 1000,
"totalSpent": 400
}
}
HTTP 401
Unauthorized
Content type: application/json.
Unknown properties are rejected. Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.error | string | Yes | Error type |
response.message | string | No | Human-readable error message |
HTTP 500
Internal server error
Content type: application/json.
Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.error | string | Yes | Error type |
response.message | string | No | Human-readable error message |
Example response
{
"error": "Failed to get credit balance"
}
Schema definitions
The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.
CreditBalance
Unknown properties are rejected. Required properties: balance, subscriptionCredits, addonCredits.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
CreditBalance.balance | integer | Yes | Total available credits from subscription and add-on pools |
CreditBalance.subscriptionCredits | integer | Yes | Credits remaining in the current subscription period |
CreditBalance.addonCredits | object | Yes | Add-on credit pool and historical add-on totals Unknown properties are rejected. Required properties: balance, totalEarned, totalSpent. |
Nested field: CreditBalance.addonCredits
Add-on credit pool and historical add-on totals
Unknown properties are rejected. Required properties: balance, totalEarned, totalSpent.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
CreditBalance.addonCredits.balance | integer | Yes | Available add-on credits |
CreditBalance.addonCredits.totalEarned | integer | Yes | Total add-on credits earned over all time |
CreditBalance.addonCredits.totalSpent | integer | Yes | Total add-on credits spent over all time |
AuthenticationError
Unknown properties are rejected. Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
AuthenticationError.error | string | Yes | Error type |
AuthenticationError.message | string | No | Human-readable error message |
Error
Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
Error.error | string | Yes | Error type |
Error.message | string | No | Human-readable error message |