GET
/
v1
/
billing
/
{organizationId}
/
credits
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.billing.getCreditBalance({
  organizationId: process.env.OCTOSPARK_ORGANIZATION_ID ?? "organizationId",
})
{
  "creditsBalanceDecimillicents": 123,
  "reservedCreditsDecimillicents": 123,
  "availableDecimillicents": 123,
  "creditsBalanceDollars": 123,
  "reservedCreditsDollars": 123,
  "availableDollars": 123,
  "isSuspended": true,
  "suspendedAt": "2026-06-10T14:32:00Z",
  "paymentGracePeriodEndsAt": "2026-06-17T14:32:00Z",
  "activeHolds": [
    {
      "holdKey": "agent_tool:ingest_source",
      "message": "<string>",
      "uncertainExposureDecimillicents": 123,
      "uncertainExposureDollars": 123,
      "settlementReferenceIds": [
        "<string>"
      ]
    }
  ],
  "accountSpendCap": {
    "limitDecimillicents": 123,
    "spentDecimillicents": 123,
    "heldDecimillicents": 123,
    "periodStart": "<string>",
    "resetsAt": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
organizationId
string
required

Organization id (UUID). Discover ids via the list organizations endpoint or the agent context.

Response

Success

​
creditsBalanceDecimillicents
number
required

Total credit balance in decimillicents (10000000 = $1), including credits currently reserved by in-flight operations.

Example:

200000000

​
reservedCreditsDecimillicents
number
required

Credits in decimillicents currently held by in-flight reservations (e.g. pending publishes or AI calls).

Example:

20000

​
availableDecimillicents
number
required

Spendable credits in decimillicents: balance minus reserved.

Example:

199980000

​
creditsBalanceDollars
number
required

creditsBalanceDecimillicents expressed in dollars (decimillicents / 10,000,000), for display without unit conversion.

Example:

20

​
reservedCreditsDollars
number
required

reservedCreditsDecimillicents expressed in dollars.

Example:

0.002

​
availableDollars
number
required

availableDecimillicents expressed in dollars: what the org can spend right now.

Example:

19.998

​
isSuspended
boolean
required

True when the org is blocked from ALL new credit-consuming operations: suspended (usage cap exceeded, open dispute), inside an unresolved failed-payment grace period, or under any organization-scope hold in activeHolds. A category hold alone leaves this false.

​
suspendedAt
string | null
required

ISO 8601 timestamp of when the org was suspended, or null when the org is healthy.

Example:

"2026-06-10T14:32:00Z"

​
paymentGracePeriodEndsAt
string | null
required

ISO 8601 end of the current failed-payment grace period, or null when there is no unresolved payment failure; only a successful payment clears it, wall-clock expiry does not unblock the org.

Example:

"2026-06-17T14:32:00Z"

​
activeHolds
object[]
required

Every hold that would refuse a new paid reservation right now. 'category' holds pause only the named operation (an earlier charge awaits reconciliation); 'organization' holds pause all paid work. Empty when nothing is held.

​
accountSpendCap
object
required

The account monthly spend cap and this UTC month's spend against it, or null when the spend could not be read (the balance is still returned). A reserve over the cap is refused with 402 reason budget_limit once the mode is enforce.