> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt > Use this file to discover all available pages before exploring further. # Get a customer's agent balance > The mode-shaped live balance: the wallet shadow balance (wallet minus unsettled, correct the instant a consume commits), the credit pot, or every rolling window's remaining allowance with its reset instant — decided by the scope's mode. `agents` lists each agent with a pool of its own. This is the operator's read of what the runtime `snapshot` endpoint answers the customer's integration. ## OpenAPI ````yaml get /v1/ai/billing/customers/{customer_id}/balance openapi: 3.1.0 info: title: Hyperline API version: 0.0.0 servers: - url: https://api.hyperline.co - url: https://sandbox.api.hyperline.co security: [] paths: /v1/ai/billing/customers/{customer_id}/balance: get: tags: - AI > Billing summary: Get a customer's agent balance description: >- The mode-shaped live balance: the wallet shadow balance (wallet minus unsettled, correct the instant a consume commits), the credit pot, or every rolling window's remaining allowance with its reset instant — decided by the scope's mode. `agents` lists each agent with a pool of its own. This is the operator's read of what the runtime `snapshot` endpoint answers the customer's integration. operationId: getAgentCustomerBalance parameters: - schema: type: string required: true name: customer_id in: path - schema: type: string minLength: 1 maxLength: 128 description: >- Agent scope identifier. Null on scoped results denotes the customer's shared pool. example: support required: false description: >- Agent scope identifier. Null on scoped results denotes the customer's shared pool. name: agent in: query responses: '200': description: '' content: application/json: schema: type: object properties: agent: type: - string - 'null' description: >- Agent scope identifier. Null on scoped results denotes the customer's shared pool. example: support mode: type: - string - 'null' enum: - wallet - credits - windows description: >- Billing mode. - wallet: Charges a monetary wallet. - credits: Consumes a credit balance. - windows: Meters weighted units against rolling allowances. example: wallet balance: type: object properties: currency: type: - string - 'null' enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: >- ISO 4217 currency code for monetary values. Null for counts or historical amounts without recorded currency. example: USD denomination: type: string enum: - minor_units - credits - units description: >- Unit of account for amounts. - minor_units: Fractional minor units of the accompanying currency. - credits: Credit counts, without a currency. - units: Weighted rolling-allowance units, without a currency. example: minor_units wallet: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Settled wallet balance, credit balance, or included allowance, in the accompanying denomination. example: '10000' unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Unsettled monetary consumption or used allowance units, in the accompanying denomination. example: '12.5' available: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Available amount in the accompanying denomination. May be negative for a wallet. example: '9987.5' required: - currency - denomination - wallet - unsettled - available description: Current balance in the accompanying denomination. example: currency: USD denomination: minor_units wallet: '10000' unsettled: '12.5' available: '9987.5' blocked: type: boolean description: Whether spending is disabled for this billing scope. example: false policy: type: - object - 'null' properties: markup_percent: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Percentage added to resolved cost. Null on writes means no override; an attached plan may supply the value. example: '20' floor: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Minimum available balance a spend check requires, in the policy's denomination. example: '0' settlement_interval_minutes: type: - number - 'null' description: >- Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule. example: 60 required: - markup_percent - floor - settlement_interval_minutes description: >- Billing rules resolved for this scope, or null when unconfigured. example: null meters: type: - array - 'null' items: type: object properties: key: type: string description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens included_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Weighted units included in one allowance window, as an exact decimal string. example: '10000' used_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Allowance units already consumed in the current window. example: '2500' remaining_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: Unconsumed allowance units, clamped at zero. example: '7500' window_started_at: type: - string - 'null' format: date-time description: >- Window started at, as a UTC ISO 8601 timestamp. Null when unavailable. example: '2026-09-02T00:00:00Z' resets_at: type: - string - 'null' format: date-time description: >- Resets at, as a UTC ISO 8601 timestamp. Null when unavailable. example: '2026-09-03T00:00:00Z' required: - key - included_units - used_units - remaining_units - window_started_at - resets_at description: >- Current state of every rolling allowance window, or null outside windows mode. example: - key: daily included_units: '10000' used_units: '2500' remaining_units: '7500' window_started_at: '2026-09-02T00:00:00Z' resets_at: '2026-09-03T00:00:00Z' credits: type: - object - 'null' properties: balance: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: Current balance in the accompanying denomination. example: '10000' currency: type: 'null' description: >- ISO 4217 currency code for monetary values. Null for counts or historical amounts without recorded currency. example: null product_id: type: string description: Public product identifier for this credit balance. example: prd_credits low_balance_threshold: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Credit balance threshold for low-balance alerts, or null when unset. example: '1000' expiring_soon: type: array items: type: object properties: amount: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Exact amount in the accompanying denomination; monetary ledger amounts are fractional minor units. example: '12.5' expires_at: type: string format: date-time description: Credit expiry instant in UTC ISO 8601 format. example: '2026-10-01T00:00:00Z' required: - amount - expires_at description: >- Credit grants expiring within 30 days. Amounts are original grants, not remaining balances. example: - amount: '10000' expires_at: '2026-10-01T00:00:00Z' rate_card_summary: type: object properties: llm_rows: type: number description: Number of LLM pricing rows. example: 1 item_rows: type: number description: Number of item rows. example: 0 has_default_llm_row: type: boolean description: >- Whether a wildcard LLM row supplies rates for otherwise unmatched models. example: true fallback_credits_per_usd: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Credits charged per USD of unmatched provider cost. Omission leaves unmatched usage unpriced. example: '1000' required: - llm_rows - item_rows - has_default_llm_row - fallback_credits_per_usd description: >- Summary of the pricing available to this credit balance. example: llm_rows: 1 item_rows: 0 has_default_llm_row: true fallback_credits_per_usd: '1000' required: - balance - currency - product_id - low_balance_threshold - expiring_soon - rate_card_summary description: >- Credit balance and product details, or null outside credits mode. example: null overage: type: - object - 'null' properties: currency: type: - string - 'null' enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: >- ISO 4217 currency code for monetary values. Null for counts or historical amounts without recorded currency. example: USD mode: type: string enum: - refuse - metered description: >- Behavior when credits or an allowance are exhausted. Policy values may inherit the attached plan. - refuse: Rejects the call that crosses the boundary without deducting usage. - metered: Prices the whole call as monetary overage, using the overage card or USD provider cost plus markup. example: metered active: type: boolean description: >- Whether the scope has exhausted its included credits or allowance. example: false unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Unsettled monetary consumption or used allowance units, in the accompanying denomination. example: '12.5' required: - currency - mode - active - unsettled description: >- Overage policy, current boundary status and unsettled monetary balance; null in wallet mode. example: currency: USD mode: metered active: false unsettled: '0' last_settled_at: type: - string - 'null' format: date-time description: >- Last settled at, as a UTC ISO 8601 timestamp. Null when unavailable. example: '2026-09-02T00:00:00Z' agents: type: array items: type: object properties: agent: type: string description: >- Agent scope identifier. Null on scoped results denotes the customer's shared pool. example: support mode: type: string enum: - wallet - credits - windows description: >- Billing mode. - wallet: Charges a monetary wallet. - credits: Consumes a credit balance. - windows: Meters weighted units against rolling allowances. example: wallet balance: type: object properties: currency: type: - string - 'null' enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: >- ISO 4217 currency code for monetary values. Null for counts or historical amounts without recorded currency. example: USD denomination: type: string enum: - minor_units - credits - units description: >- Unit of account for amounts. - minor_units: Fractional minor units of the accompanying currency. - credits: Credit counts, without a currency. - units: Weighted rolling-allowance units, without a currency. example: minor_units wallet: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Settled wallet balance, credit balance, or included allowance, in the accompanying denomination. example: '10000' unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Unsettled monetary consumption or used allowance units, in the accompanying denomination. example: '12.5' available: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Available amount in the accompanying denomination. May be negative for a wallet. example: '9987.5' required: - currency - denomination - wallet - unsettled - available description: Current balance in the accompanying denomination. example: currency: USD denomination: minor_units wallet: '10000' unsettled: '12.5' available: '9987.5' blocked: type: boolean description: Whether spending is disabled for this billing scope. example: false meters: type: - array - 'null' items: type: object properties: key: type: string description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens included_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Weighted units included in one allowance window, as an exact decimal string. example: '10000' used_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Allowance units already consumed in the current window. example: '2500' remaining_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: Unconsumed allowance units, clamped at zero. example: '7500' window_started_at: type: - string - 'null' format: date-time description: >- Window started at, as a UTC ISO 8601 timestamp. Null when unavailable. example: '2026-09-02T00:00:00Z' resets_at: type: - string - 'null' format: date-time description: >- Resets at, as a UTC ISO 8601 timestamp. Null when unavailable. example: '2026-09-03T00:00:00Z' required: - key - included_units - used_units - remaining_units - window_started_at - resets_at description: >- Current state of every rolling allowance window, or null outside windows mode. example: - key: daily included_units: '10000' used_units: '2500' remaining_units: '7500' window_started_at: '2026-09-02T00:00:00Z' resets_at: '2026-09-03T00:00:00Z' overage: type: - object - 'null' properties: currency: type: - string - 'null' enum: - EUR - AED - AFN - XCD - ALL - AMD - AOA - ARS - USD - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - XOF - BMD - BND - BOB - BRL - BSD - BTN - NOK - BWP - BYR - BZD - CAD - CDF - XAF - CHF - NZD - CLP - CNY - COP - CRC - CUP - CVE - ANG - CZK - DJF - DKK - DOP - DZD - EGP - MAD - ERN - ETB - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - XPF - NGN - NIO - NPR - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - UYU - UZS - VEF - VND - VUV - WST - YER - ZAR - ZMW - ZWL description: >- ISO 4217 currency code for monetary values. Null for counts or historical amounts without recorded currency. example: USD mode: type: string enum: - refuse - metered description: >- Behavior when credits or an allowance are exhausted. Policy values may inherit the attached plan. - refuse: Rejects the call that crosses the boundary without deducting usage. - metered: Prices the whole call as monetary overage, using the overage card or USD provider cost plus markup. example: metered active: type: boolean description: >- Whether the scope has exhausted its included credits or allowance. example: false unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Unsettled monetary consumption or used allowance units, in the accompanying denomination. example: '12.5' required: - currency - mode - active - unsettled description: >- Overage policy, current boundary status and unsettled monetary balance; null in wallet mode. example: currency: USD mode: metered active: false unsettled: '0' required: - agent - mode - balance - blocked - meters - overage description: Agent scopes with their own policy or consumption history. example: [] required: - agent - mode - balance - blocked - policy - meters - credits - overage - last_settled_at - agents '400': description: Invalid request. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: Customer not found content: application/json: schema: type: object properties: message: type: string required: - message '409': description: The request conflicts with the current configuration. content: application/json: schema: type: object properties: message: type: string required: - message security: - bearer: [] components: securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.