Credits

Org prepaid credit balance and usage spend for one billing cycle, plus credit top-up: the HTTP mirror of ax credit. Amounts are USD prepaid credits reported in micros (1 credit dollar = 1_000_000 micros).

Every route takes org_id (required only when the key can see several orgs). Parameters are optional unless marked required.

Payment itself never happens over this API. Reload returns a hosted Stripe Checkout URL that a human opens in a browser, and no card data passes through /api/v1.

Authorization

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

The two read routes select one org UTC calendar billing cycle with period:

An invalid token returns 400 invalid_argument. A valid period with no matching cycle returns 404 not_found.

A billing cycle follows your plan anniversary, not the calendar, so one month can contain two cycles: a mid-month plan change starts a new one. YYYY-MM then selects the cycle you ended that month on, and the earlier one is what previous returns while that cycle is current. Read periodStart / periodEnd on the response to see exactly which window answered.

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.

Credit expiry

The balance buckets do not have the same lifetime:

Credits are spent in expiry order: base plan credit first, then increment plan credit, then on-demand credit. totalBalanceMicros therefore mixes money with different lifetimes; read the per-bucket fields if you need to know what is durable.

Changing plan never writes credit off. Upgrading mid-cycle keeps your current base credit to its original expiry and adds a prorated base top-up that aligns you to your new billing cycle, alongside the full increment. Downgrading forfeits nothing: increment credit you were already granted stays spendable until its own expiry.

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"

GET /api/v1/credits/spend

Usage spend for one billing cycle. Admins see org-wide totals, optionally grouped or filtered; members receive their own spend.

curl -H "Authorization: Bearer $AX_API_KEY" \
  "https://app.514.ax/api/v1/credits/spend?group_by=experiment&include_byok=true"

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".

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"

POST /api/v1/credits/reload

Buy prepaid credit for the org. Org admin only.

The platform mints a hosted Stripe Checkout session (mode: payment), the same session the web Buy credits flow creates, and returns its URL. Payment always completes in a browser on Stripe: this route never accepts card details, and credit is posted by the Stripe webhook once the session is paid, not when this call returns.

curl -X POST -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountUsd": "50"}' \
  "https://app.514.ax/api/v1/credits/reload"

The amount must be between $5 and $5,000, the same bounds as the web custom-amount purchase and ax credit reload. Malformed amounts (negatives, more than two decimals, exponents, thousands separators, JSON numbers) return 400 invalid_argument. An org_id in the body is ignored; the org comes from the key, with the org_id query parameter when the key can see several orgs.