Skip to main content
GET
/
api
/
credits
/
balance
Get credit balance
curl --request GET \
  --url https://api.example.com/api/credits/balance
{
  "balance": 123,
  "tier": "<string>",
  "tierDisplayName": "<string>",
  "monthlyAllocation": 123,
  "nextRefreshDate": "<string>",
  "stats": {
    "totalEarned": 123,
    "totalSpent": 123,
    "lifetimeBalance": 123
  }
}
Returns the authenticated user’s current credit balance, monthly tier allocation, and tier details.

​
Request

​
includeStats
boolean
default:"false"
Include additional statistics (total earned, spent, etc.)

​
Response

​
balance
integer
required
Current available credits
​
tier
string
required
Current tier key (e.g., “free”, “joi-curious”, “full-access”, “vip”)
​
tierDisplayName
string
required
Human-readable tier name
​
monthlyAllocation
integer
required
Credits allocated monthly for this tier
​
nextRefreshDate
string
ISO timestamp of next monthly credit refresh
​
stats
object
Additional statistics (only if includeStats=true)

​
Example Request

curl https://your-domain.com/api/credits/balance \
  -H "Cookie: connect.sid=your-session-cookie"

​
Example Response

{
  "balance": 127,
  "tier": "joi-curious",
  "tierDisplayName": "JOI-Curious",
  "monthlyAllocation": 1000,
  "nextRefreshDate": "2026-04-01T00:00:00.000Z"
}

​
Response Codes

CodeDescription
200Success - Returns credit balance
401Unauthorized - User not authenticated
500Server error

​
Notes

  • Balance is checked before any credit-consuming operation
  • Monthly allocations reset on the 1st of each month
  • Free tier users receive 50 credits per month
  • Premium tiers receive larger monthly allocations (1,000 - 5,000)

Build docs developers (and LLMs) love

Get started for freeTalk to us