Endpoints

Account status

Returns the credit balance and subscription of the account behind your API key. A pure read: nothing is charged.

GET/api/v1/accountFree

This is the endpoint to call before a batch of generations, or when a scheduled workflow wakes up: one round trip tells you how much you have left and whether your subscription still holds. No parameters, no request body — your key alone decides what comes back.

The only endpoint callable at 0 credits

The three production routes answer 402 as soon as the balance hits zero. This one stays open: an endpoint whose job is to tell you « no credits left » would be useless if it were the first to close.

Headers

Request headers

Parameter	Type	Required	Description
`Authorization`	`string`	Required	Your API key, prefixed with `Bearer`. A missing, unknown or revoked key returns `401`.

Example

cURL

curl -s https://subreply.io/api/v1/account \
  -H "Authorization: Bearer sr_live_YOUR_API_KEY"

200 response

{
  "credits": {
    "monthly_remaining": 320,
    "purchased_remaining": 150,
    "total_remaining": 470
  },
  "subscription": {
    "status": "active",
    "plan": "starter"
  }
}

Account without a subscription

{
  "credits": {
    "monthly_remaining": 0,
    "purchased_remaining": 0,
    "total_remaining": 0
  },
  "subscription": {
    "status": "none",
    "plan": null
  }
}

Response fields

Field	Type	Description
`credits.monthly_remaining`	number	Credits from the current month still available. They are renewed every billing period and do not carry over.
`credits.purchased_remaining`	number	Credits bought one by one, still available. They never expire.
`credits.total_remaining`	number	The sum of both. This is the total the production routes compare against the cost of a call.
`subscription.status`	string	Subscription state (see the table below).
`subscription.plan`	string \| null	Plan name, or null if the account never subscribed. Only one plan exists today.

The response carries no email address, no Stripe identifier and no account id: an API key says what it can do, not who holds it.

Subscription statuses

Status	What it means
`active`	Paid subscription running.
`past_due`	A payment failed. The subscription is not cancelled yet, but the payment method needs updating.
`canceled`	Subscription cancelled. Purchased credits remain usable, monthly credits are no longer renewed.
`none`	This account has never subscribed.

Errors

Two cases only: 401 when the key is missing or invalid, and 503 when the balance could not be read. A 503 does not mean « empty account » but « balance unavailable »: retry rather than conclude. Details are on the error codes page.