get__credits_balance

GET /credits/balance

Get Credit Balance

Returns the organization's credit balance for the authenticated user. Includes the stored balance (through dateBalance), realtime balance (minus pending consumption since that date), and a breakdown of pending consumption by storage and AI. Only available when the platform is configured with SUBSCRIPTION_SYSTEM=credits.

TypeScript Client Library

public getCreditsBalance = async (): Promise<GetCreditsBalanceResponse> => {
  return this.makeRequest<GetCreditsBalanceResponse>('credits/balance', 'GET', null);
};

Code Samples

Shell

curl -X GET https://backend.flashback.tech/credits/balance \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

HTTP

JavaScript

Python

Example responses

200 Response

{
  "success": true,
  "data": {
    "creditBalance": 5000,
    "dateBalance": "2026-01-29T00:00:00.000Z",
    "realtimeBalance": 4850.5,
    "pendingConsumption": 149.5,
    "breakdown": {
      "storage": 80.2,
      "ai": 69.3
    }
  }
}

400 Response (credits not enabled)

{
  "success": false,
  "error_code": "CREDITS_NOT_ENABLED",
  "message": "Credits system is not enabled"
}

404 Response

{
  "success": false,
  "error_code": "USER_NOT_FOUND",
  "message": "User not found"
}

500 Response

{
  "success": false,
  "error_code": "INTERNAL_ERROR",
  "message": "Failed to retrieve credit balance"
}

Responses

Status	Meaning	Description	Schema
200	OK	Credit balance and breakdown	Inline
400	Bad Request	Credits not enabled or no organization	Inline
404	Not Found	User not found	Inline
500	Internal Server Error	Server error	Inline

Response Schema (200)

Name	Type	Required	Description
» success	boolean	false	Whether the request succeeded
» data	object	false	Balance data
»» creditBalance	number	false	Stored balance through dateBalance
»» dateBalance	string (date-time) | null	false	Last UTC date through which consumption was applied
»» realtimeBalance	number	false	creditBalance minus pending consumption
»» pendingConsumption	number	false	Consumption since dateBalance (not yet in stored balance)
»» breakdown	object	false	Pending consumption by category
»»» storage	number	false	Pending credits from storage egress
»»» ai	number	false	Pending credits from AI token usage
» error_code	string	false	Set on error
» message	string	false	Error or status message

Security

• BearerAuth: Bearer token required.

• Organization: User must belong to an organization; balance is for that organization.

Notes

• Returns 400 with CREDITS_NOT_ENABLED when SUBSCRIPTION_SYSTEM is not credits.

• realtimeBalance is the effective balance for enforcement (stored balance minus consumption since dateBalance).