Read account MCP response

Interpret the account plan, usable credits, personal allowance, and pay-as-you-go spending headroom returned by Read_Account.

Returned by: Read account MCP tool
Response type: Advisory account snapshot

Response Shape

The response contains structured content and a short human-readable summary of the same snapshot. The plan, credits, caller_allowance, and payg sections, and each item in capabilities, report whether their information is available or unknown. An available section can describe blocked usage; check its available or usable field and reason_codes. Unknown values are never zero or unlimited. Observation times describe local reads, not a guaranteed atomic snapshot of every section or a live invoice refresh.

Field	Type	Notes
`schema_version`	integer	Currently 1.
`observed_at`	string	ISO 8601 observation time.
`snapshot_kind`	string	`advisory_local_snapshot`.
`account`	object	Account display name.
`plan`	object	Effective plan key/name, entitlement status, active entitlement, external management, trial/end/period dates, and a separate pending change when present. Unknown billing state returns a reason instead.
`credits`	object	Estimated `available_microcredits`, `microcredits_per_credit`, and display `available_credits`; includes unexpired purchased, promotional and included credits less recorded outstanding usage. Unknown/inconsistent balances return null amounts.
`caller_allowance`	object	The caller's effective `limit_microcredits`, `charged_microcredits`, `remaining_microcredits`, `allows_new_work`, period/reset, and pending-setting indicator. An uncapped personal allowance has null limit and remaining amounts.
`payg`	object	Configured and usable states, reasons, USD currency, effective monthly cap, recorded spend, remaining headroom, period/reset, and pending-setting indicator. Money is integer cents. Only account owners and administrators receive exact amounts; other members receive `amounts_status: "redacted"` with null cap, spend and headroom amounts in structured content and no exact amounts in text.
`capabilities`	object	Account prerequisites for `mcp_credit_usage`, `main_ai`, and `automations`. Each reports availability and reason codes. Main AI also reports its billing mode and any monthly new-conversation limit/usage/reset; creation permissions are reported for AI and automations.
`capability_scope`	string	Explains coverage and remaining tool, OAuth, resource and model checks. Missing capabilities are unreported.
`next_actions`	object	Account/credits/Sales links, whether the caller can manage credits, and recovery/polling guidance.

Pay-as-you-go amounts_status distinguishes redacted (permission-restricted) from unknown (incomplete accounting) and available. Redaction does not mean zero or uncapped.

Pay-as-you-go remaining_headroom_cents is the effective cap minus recorded spend, floored at zero. With cap_state: "uncapped", the cap and headroom are null: there is no configured enforced monthly cap. Pay-as-you-go can still be blocked by payment eligibility, settings or other restrictions. When price/accounting information is unknown, headroom can also be null; use status and cap_state to distinguish these cases.

Prepaid credits and pay-as-you-go dollars are separate. Headroom is not an outstanding invoice balance or a final invoice estimate. A reached pay-as-you-go cap can coexist with usable prepaid credits. A personal allowance can block work even while account credits remain. Saved pending caps and personal limits do not replace their effective values until applied.

Main AI plan-included access does not imply that ordinary MCP calls are free. The capability snapshot covers account prerequisites; it does not grant tool-specific OAuth permissions, access to individual records, or access to every AI model. Plan monthly conversation usage applies to new conversations; existing conversation behavior remains subject to its normal checks.

Follow-up Behavior

On credits_depleted, review credits and contact an administrator or Sales early enough for procurement.
On user_credit_limit_reached or plan_ai_limit_reached, check the reported reset time or ask an administrator about the limit.
On payg_disabled, payg_not_eligible, or payg_payment_method_required, review the account's settings with an administrator. Inspection does not enable billing.
On payg_cap_reached, check remaining prepaid credits and the caller allowance before deciding all work is blocked.
On billing_setup_pending, usage_suspended, active_entitlement_required, credit_billing_unavailable, credits_not_enabled, main_ai_not_included, or permission_required, use the account link and the relevant administrator or Sales contact.
On billing_temporarily_unavailable, credit_balance_temporarily_unavailable, spending_temporarily_unavailable, spending_pricing_unavailable, or funding_temporarily_unavailable, retry later without treating null values as zero. Contact support if the condition persists.
On credit_accounting_inconsistent or credit_expiry_unknown, contact support. No spendable balance is asserted.

The tool does not reserve credits or spending capacity. Concurrent work and later settlement can change availability. No per-source allocation or expiry schedule for outstanding usage is asserted.

Example

This synthetic excerpt illustrates independent credit and pay-as-you-go quantities; other response sections are omitted here.

{
  "credits": {
    "status": "available",
    "available_microcredits": 2500,
    "microcredits_per_credit": 10,
    "available_credits": 250,
    "is_estimate": true
  },
  "payg": {
    "status": "available",
    "configured": true,
    "usable": true,
    "reason_codes": [],
    "currency": "USD",
    "cap_state": "capped",
    "effective_monthly_cap_cents": 10000,
    "recorded_spend_cents": 1800,
    "remaining_headroom_cents": 8200,
    "period": "2026-11",
    "resets_at": "2026-12-01T00:00:00+00:00",
    "settings_pending": false
  }
}

This account has 250 estimated prepaid credits and $82 of pay-as-you-go headroom. These values must not be added into one balance.

Response Shape

Follow-up Behavior

Example

On this page