---
updatedAt: 2026-08-24T09:14:57.000Z
agentTools:
projectIndex: https://developers.vibe.co/llms.txt
---
# Get account balance
Returns the current balance in cents for the authenticated account. This is the authoritative figure for what is owed; it is read from a running total, not summed from the operations list, so the two are not expected to match exactly.
**Scopes:**
`billing:read`
*Rate limits*:
Burst: `10/s`
Steady: `300/m`
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"paths": {
"/billing/balance": {
"get": {
"description": "Returns the current balance in cents for the authenticated account. This is the authoritative figure for what is owed; it is read from a running total, not summed from the operations list, so the two are not expected to match exactly.\n**Scopes:**\n`billing:read`\n
*Rate limits*:
Burst: `10/s`
Steady: `300/m`\n",
"operationId": "getAccountBalance",
"parameters": [
{
"name": "account_id",
"required": false,
"in": "query",
"description": "Required only for embedded apps.",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": "Account balance",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Balance"
}
}
}
},
"400": {
"description": "Bad request error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"missingApiKey": {
"summary": "Missing API key",
"value": {
"error": {
"type": "validation",
"message": "Missing API Key",
"status": 400,
"detail": null,
"request_id": "req_8f3a4b2c",
"doc_url": null
}
}
},
"validationError": {
"summary": "Validation error",
"value": {
"error": {
"type": "validation",
"message": "Validation error",
"status": 400,
"detail": {
"validation": [
"id must be a string"
]
},
"request_id": "req_8f3a4b2c",
"doc_url": null
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"invalidApiKey": {
"summary": "Invalid API key",
"value": {
"error": {
"type": "invalid_token",
"message": "Unauthorized",
"status": 401,
"detail": null,
"request_id": "req_8f3a4b2c",
"doc_url": "https://developers.vibe.co/errors/invalid-token"
}
}
}
}
}
}
},
"403": {
"description": "Insufficient scope error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"insufficientScope": {
"summary": "Missing required scope",
"value": {
"error": {
"type": "insufficient_scope",
"message": "Missing required scope",
"status": 403,
"detail": {
"required": "billing:read",
"granted": [
"test"
]
},
"request_id": "req_8f3a4b2c",
"doc_url": "https://developers.vibe.co/reference/oauth2token"
}
}
}
}
}
}
}
},
"summary": "Get account balance",
"tags": [
"Billing"
],
"x-rate-limit": {
"rps": 10,
"rpm": 300
},
"x-scopes": [
"billing:read"
]
}
}
},
"info": {
"title": "Vibe Public API",
"description": "Vibe Public API revision 2026-06-01",
"version": "2026-06-01",
"contact": {}
},
"tags": [
{
"name": "Billing",
"description": "Read-only views of what an Account owes and has spent. All amounts are in cents.\n\nThe balance is the authoritative figure for what is owed. It is read from a running total rather than summed from the cash-operations list, so the two are not expected to match exactly.\n\nCash operations are grouped into one entry per calendar day per type, in the account timezone, matching what the Vibe app shows. `amount_cents` is rounded per entry, so use `total_amount_cents` for an exact total over a window.\n\n> ⚠️ **Gotcha — operation windows are bounded by volume, not duration**\n>\n> A window covering more than 50,000 operations is rejected with `400`. Ad spend is recorded hourly, so a one-year window is well inside that; only windows spanning several years of continuous spend approach it. Narrow `from`/`to` if you hit it: the window is aggregated before `limit`/`offset` are applied, so paging cannot bring an oversized one under the limit."
}
],
"servers": [
{
"url": "https://api.vibe.co",
"description": "Production API"
}
],
"components": {
"securitySchemes": {
"bearer": {
"scheme": "bearer",
"bearerFormat": "JWT",
"type": "http"
}
},
"schemas": {
"ErrorDetail": {
"type": "object",
"properties": {
"required": {
"type": "string",
"example": "audiences:write"
},
"granted": {
"example": [
"audiences:read",
"reporting:read"
],
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"required",
"granted"
]
},
"ApiError": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"insufficient_scope",
"invalid_token",
"validation",
"internal_error"
]
},
"message": {
"type": "string"
},
"status": {
"type": "number",
"example": 403
},
"detail": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/ErrorDetail"
}
]
},
"request_id": {
"type": "string",
"example": "req_8f3a4b2c"
},
"doc_url": {
"type": "string",
"example": "https://developers.vibe.co/reference/oauth2token",
"nullable": true
}
},
"required": [
"type",
"message",
"status",
"request_id"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"$ref": "#/components/schemas/ApiError"
}
},
"required": [
"error"
]
},
"Balance": {
"type": "object",
"properties": {
"account_id": {
"type": "number",
"description": "Account (tenant) identifier"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code",
"example": "usd"
},
"balance_cents": {
"type": "number",
"description": "Current balance in cents (integer, no decimals)"
},
"updated_at": {
"type": "object",
"nullable": true,
"description": "When the balance was last updated",
"format": "date-time"
}
},
"required": [
"account_id",
"currency",
"balance_cents",
"updated_at"
]
}
}
},
"security": [
{
"bearer": []
}
]
}
```