Get account balance
Get remaining credit balance before running large batches of metered tools — Get account balance.
Headers
Get your API keyAPI key (`sfk_...`)
Endpoint-specific response payload.
Spendable credits. Grace buffer counts only after included and PAYG credits are exhausted.
≥ 0
Total PAYG bucket, including pre-granted grace not yet spendable.
≥ 0
PAYG credits spendable before grace. Equals `payg` when not in grace.
≥ 0
Grace buffer for the current unpaid refill episode (0 if none). Excluded from `balance` until spendable credits are spent.
≥ 0
Auto-refill state: `healthy`, `grace`, or `exhausted`. Null when auto-refill is off.
one of: healthy, grace, exhausted, null
Billing health: `none`, `payment_action_required`, or `suspended`. Check alongside `balance` for alerts.
one of: none, payment_action_required, suspended
Included credits left this period (0 if not subscribed).
≥ 0
Included credits granted this period (0 if not subscribed).
≥ 0
Subscription summary, or `null` for PAYG-only callers.
Subscription tier (e.g. `starter`).
Subscription status (e.g. `active`, `past_due`).
When the current included-credit period ends (ISO 8601).
Subscription collection status.
one of: current, base_past_due, suspended
Metadata describing the request and billing outcome.
Unique request identifier for tracing this API call.
min 1 chars
Credits charged for this request.
≥ 0
Public API version that served the response.
one of: v1
True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.
Code example
curl "https://api.socialfetch.dev/v1/balance" \
-H "x-api-key: YOUR_API_KEY"Responses
OK