Skip to main content
POST
Check AI spend allowance

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Check payload.

​
customer
string
required

Customer to bill — the external id your application knows them by, or a Hyperline cus_… id. Resolved exactly the way AI telemetry resolves it.

Required string length: 1 - 255
Example:

"acme-corp"

​
agent
string

The agent making the call, as run({ agent }) names it. Optional, and absent means the customer's shared pool — which is what every call did before per-agent billing existed. Naming an agent only changes anything once an operator has given that agent a billing policy of its own; until then it resolves to the same shared pool and the response says so with agent: null.

Required string length: 1 - 128
Example:

"invoice-copilot"

​
action
string

Optional action name. Accepted and reserved for per-action allowances; it does not change the verdict in any mode today.

Required string length: 1 - 128
Example:

"deep_research"

Response

Verdict.

​
agent
string | null
required

The billing scope that answered: the agent's own slug when it has a policy of its own, and null when the customer's shared pool answered — including when an agent was named but has no policy of its own.

Example:

"invoice-copilot"

​
allowed
boolean
required

Whether the customer may spend right now.

Example:

true

​
reason
enum<string> | null
required

Reason spending was denied. Null when allowed.

  • not_configured: No billing policy is configured.
  • unsupported_mode: The billing configuration is unsupported.
  • customer_not_found: The customer could not be found.
  • wallet_missing: The monetary wallet is unavailable.
  • credit_pot_missing: The credit balance is unavailable.
  • blocked: Spending is disabled for the scope.
  • insufficient_balance: The wallet balance is at or below the policy floor.
  • insufficient_credits: The credit balance cannot cover the required spend.
  • allowance_exhausted: A rolling allowance has no room for the spend.
  • windows_not_configured: Rolling allowance definitions are missing.
Available options:
not_configured,
unsupported_mode,
customer_not_found,
wallet_missing,
credit_pot_missing,
blocked,
insufficient_balance,
insufficient_credits,
allowance_exhausted,
windows_not_configured
Example:

null

​
balance
object
required

What the customer can spend. In wallet mode this is the shadow balance — micro-consumption never touches the wallet ledger directly. In credits mode it is the credit pot itself, read live. In windows mode the three numbers describe the binding window, the one with least room left and therefore the one that will refuse the next call; meters carries every window separately.

Example:
​
meters
object[] | null
required

Every rolling allowance window, in windows mode. Null in every other mode. allowed is false as soon as any one of them is at or below the policy floor.

Example:
​
overage
boolean
required

True when this allowed: true is an overage verdict — the scope is past its boundary and the next call will be priced in the overage currency rather than refused. Never a denial of its own: allowed still answers "may I proceed".

Example:

true