Credits
ReferenceUpdated June 14, 2026
Credits
Inspect your workspace's credit balance, plan, usage, and pay-as-you-go (PAYG) status, and run a pre-flight check before a billable operation. Both endpoints require the credits:read scope.
Get credit balance
GET /api/v1/credits · scope credits:read
Returns the current balance plus plan, billing period, usage, and PAYG status for the API key's workspace. (Stripe identifiers are never exposed via the API.)
Example request
curl -X GET "https://app.machfive.io/api/v1/credits" \
-H "Authorization: Bearer YOUR_API_KEY"Response (200 OK)
{
"balance": 1240,
"is_unlimited": false,
"plan": {
"tier": "pro",
"billing_cycle": "monthly",
"status": "active",
"monthly_credits_limit": 2000,
"custom_credits_limit": null
},
"period": {
"start": "2025-01-01T00:00:00.000Z",
"end": "2025-02-01T00:00:00.000Z"
},
"usage": {
"credits_used_this_period": 760,
"total_credits_used_all_time": 18230,
"monthly_allocated": 2000,
"rollover": 0,
"addon": 0
},
"payg": {
"eligible": true,
"enabled": false,
"cap_cents": 5000,
"spent_cents": 0,
"credits_used": 0,
"pct_of_cap": 0
}
}| Field | Type | Description |
|---|---|---|
balance | number | Current credit balance. |
is_unlimited | boolean | true for internal/unlimited plans. |
plan | object | Tier, billing cycle, status, and credit limits. |
period | object | Current billing period start/end (ISO 8601). |
usage | object | Credits used this period and all-time, plus allocation breakdown. |
payg | object | Pay-as-you-go eligibility, enablement, cap, and spend. |
Error responses
| Status | Error | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid API key. |
| 403 | FORBIDDEN | Key missing the credits:read scope. |
| 404 | NOT_FOUND | No subscription found for this workspace. |
| 500 | INTERNAL_ERROR | Server error. |
Check credit availability
GET /api/v1/credits/check?required=N · scope credits:read
PAYG-aware pre-flight check. Returns whether the workspace can currently cover N credits — including pay-as-you-go headroom, not just raw balance — so it can never disagree with what enforcement would do. Always responds 200; read sufficient for the outcome.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
required | number | Yes | Number of credits to check (positive integer). |
Example request
curl -X GET "https://app.machfive.io/api/v1/credits/check?required=5" \
-H "Authorization: Bearer YOUR_API_KEY"Response (200 OK)
{
"required": 5,
"sufficient": true,
"available": 1240,
"payg_enabled": false,
"pct_of_cap": 0
}| Field | Type | Description |
|---|---|---|
required | number | Echoes the requested amount. |
sufficient | boolean | Whether the workspace can cover required credits (balance or PAYG). |
available | number | Current raw credit balance. |
payg_enabled | boolean | Whether pay-as-you-go is enabled. |
pct_of_cap | number | Fraction (0–1) of the PAYG cap consumed this cycle. |
Error responses
| Status | Error | Description |
|---|---|---|
| 400 | BAD_REQUEST | Missing or invalid required. |
| 401 | UNAUTHORIZED | Missing or invalid API key. |
| 403 | FORBIDDEN | Key missing the credits:read scope. |