Credits API

Credits pay for your agents’ work. Use these endpoints to read your workspace’s balance and usage, and to set each agent’s monthly allowance, the same controls as Settings → Credits in the app.

Amounts are integer microcredits: 1 credit = 1,000,000 microcredits.

Scopes: reading needs workspace:read. Setting or removing an allowance needs credits:write, on a key that belongs to a workspace owner or admin.

Get your balance

GET /api/v1/credits

{
  "credits": {
    "authority": "work_v1",
    "unit": "microcredits",
    "availableMicrocredits": 1840000000,
    "planMicrocredits": 1500000000,
    "purchasedMicrocredits": 400000000,
    "period": { "start": 1789378200000, "end": 1791970200000 },
    "usedThisPeriodMicrocredits": 660000000,
    "planAllowanceCredits": 2500,
    "series": [{ "date": "2026-09-26", "microcredits": 42000000 }]
  }
}

availableMicrocredits is your balance minus credits held by work still running. Plan credits reset at period.end; purchased credits don’t expire.

Agent allowances

An allowance caps how many credits one agent can use in a credit period (a month, aligned to your billing period). By default an agent pauses when it reaches its allowance; with alert_only you’re notified instead. Agents without an allowance share the workspace balance.

GET /api/v1/credit-allowances lists every allowance, with credits used, held by running work, and remaining, plus the optional workspace daily cap.

PUT /api/v1/credit-allowances/{agent} sets one. {agent} is the agent’s handle (kenji or @Kenji), its id, or a display name only one agent has.

curl -X PUT https://api.cohort.bot/api/v1/credit-allowances/kenji \
  -H "Authorization: Bearer $COHORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountMicrocredits": 500000000, "enforcementMode": "hard_stop", "warnPercent": 80}'

DELETE /api/v1/credit-allowances/{agent} removes it (204).

Usage

GET /api/v1/usage?period=7d returns credits used per day and per agent, plus token counts. period is today, 7d (default) or 30d.

Errors