Credits
HTTP API routes for prepaid credit balance and usage spend.
Read-only views of org prepaid credit balance and usage spend for one billing
cycle — the HTTP mirror of ax credit. Amounts are USD prepaid
credits reported in micros (1 credit dollar = 1_000_000 micros).
| Route | Use | CLI equivalent |
|---|---|---|
GET /credits/balance | Org prepaid balance for one cycle (admin only). | ax credit balance --json |
GET /credits/spend | Usage spend for one cycle (members are self-scoped). | ax credit spend --json |
Both routes take org_id (required only when the key can see several orgs).
Parameters are optional unless marked required.
Buying credit is not on the HTTP API: use ax credit reload
or the billing UI, so payment always completes in a browser on Stripe.
Authorization
| Who | GET /credits/balance | GET /credits/spend |
|---|---|---|
| Org admin | Full org balance for the selected cycle. | Org spend; may group or filter by user or experiment. |
| Org member | 403 permission_denied. | Personal spend only — always scoped to the key's user. |
Member-restricted spend parameters return 403 permission_denied:
group_by=user, and user= naming anyone else. The denial is identical either
way, so it never reveals whether that user exists.
Billing period
Both routes select one org UTC calendar billing cycle with period:
| Value | Meaning |
|---|---|
current | Default. Cycle containing now; if none is open, the newest cycle. |
previous | Cycle immediately before the current selection. |
YYYY-MM | Cycle whose period start falls in that UTC calendar month (strict two-digit month). |
An invalid token returns 400 invalid_argument. A valid period with no matching
cycle returns 404 not_found.
Money fields
Every amount is decimal integer micros as a JSON string, never a JSON
number, so large values stay exact for scripts. Divide by 1000000 for dollars,
using a decimal or big-integer type rather than a float.
GET /api/v1/credits/balance
Remaining org prepaid credit for one billing cycle, by bucket. Org admin only.
curl -H "Authorization: Bearer $AX_API_KEY" \
"https://app.514.ax/api/v1/credits/balance?period=previous"| Parameter | What it does |
|---|---|
period | Billing cycle selector (default current). |
| Response field | Meaning |
|---|---|
periodStart, periodEnd | Selected cycle window (RFC 3339; end is exclusive). |
billingCycleId | Cycle id. |
asOf | Instant the balance is computed for: now while the cycle is open, cycle end once closed. |
currency | Currency code (USD). |
totalBalanceMicros | Remaining prepaid credit at asOf. |
freeBalanceMicros, planPaidBalanceMicros, paidBalanceMicros | The same remaining credit broken out by bucket. |
cycleFundedMicros | Funding attached to this cycle for the whole cycle — not truncated to asOf. |
GET /api/v1/credits/spend
Usage spend for one billing cycle. Admins see org-wide totals, optionally grouped or filtered; members always receive only their own spend.
curl -H "Authorization: Bearer $AX_API_KEY" \
"https://app.514.ax/api/v1/credits/spend?group_by=experiment&include_byok=true"| Parameter | What it does |
|---|---|
period | Billing cycle selector (default current). |
group_by | experiment or user — break spend into series. user is admin only. |
experiment | Limit to one experiment (id or exact display name). |
user | Limit to one user (Clerk user id or email). Admin only for another identity. |
include_byok | true or false (default false). Include BYOK attribution totals. |
Managed spend is 514-managed usage cost for the cycle: priced managed model
usage plus infrastructure run charges. BYOK attribution is reported
separately when include_byok=true and is never added into managed spend.
Without it, BYOK totals are "0".
| Response field | Meaning |
|---|---|
periodStart, periodEnd, billingCycleId, currency | Selected cycle metadata. |
groupBy, experimentId, userId | Echo of the effective grouping and filters after authorization (empty when unused; userId is the caller for members). |
totalManagedSpendMicros | Sum of managed spend across the result set. |
totalByokAttributionMicros | Sum of BYOK attribution when requested, else "0". |
series | Breakdown rows: key, label, managedSpendMicros, byokAttributionMicros. Ungrouped responses return a single total row. |
Examples:
# Your own spend for the current cycle (any member)
curl -H "Authorization: Bearer $AX_API_KEY" \
"https://app.514.ax/api/v1/credits/spend"
# Admin: one teammate in the prior cycle
curl -H "Authorization: Bearer $AX_API_KEY" \
"https://app.514.ax/api/v1/credits/spend?user=dana@acme.com&period=previous"
# Filter to one experiment by name
curl -H "Authorization: Bearer $AX_API_KEY" \
"https://app.514.ax/api/v1/credits/spend?experiment=gateway-smoke&group_by=experiment"