> ## 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 AI billing snapshot > The customer's consumption state: mode, balance, kill switch and policy. `balance` carries the same three numbers in either mode with a `denomination` saying what they count, so a consumer that only wants "how much is left" never has to branch. `credits` is populated in credits mode with the pot, its upcoming expiries and a summary of the rate card; `meters` is populated in windows mode with one live entry per rolling allowance — used, remaining and the instant it resets, counting the open instance — which is the read to poll for a limits UI. ## OpenAPI ````yaml get /v1/ai/billing/snapshot openapi: 3.1.0 info: title: Hyperline Ingest API version: 0.0.0 servers: - url: https://ingest.hyperline.co - url: https://sandbox.ingest.hyperline.co security: [] paths: /v1/ai/billing/snapshot: get: tags: - AI > Ingest summary: Get AI billing snapshot description: >- The customer's consumption state: mode, balance, kill switch and policy. `balance` carries the same three numbers in either mode with a `denomination` saying what they count, so a consumer that only wants "how much is left" never has to branch. `credits` is populated in credits mode with the pot, its upcoming expiries and a summary of the rate card; `meters` is populated in windows mode with one live entry per rolling allowance — used, remaining and the instant it resets, counting the open instance — which is the read to poll for a limits UI. operationId: getAiBillingSnapshot parameters: - schema: type: string minLength: 1 maxLength: 255 description: >- Customer to bill — the external id your application knows them by, or a Hyperline `cus_…` id. Resolved exactly the way AI telemetry resolves it. example: acme-corp required: true description: >- Customer to bill — the external id your application knows them by, or a Hyperline `cus_…` id. Resolved exactly the way AI telemetry resolves it. name: customer in: query - schema: type: string minLength: 1 maxLength: 128 description: >- 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`. example: invoice-copilot required: false description: >- 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`. name: agent in: query responses: '200': description: Snapshot. content: application/json: schema: type: object properties: agent: type: - string - 'null' description: >- 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 mode: type: - string - 'null' enum: - wallet - credits - windows description: >- Billing mode. Null when no policy is configured. - 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 amounts. 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: >- The settled source balance — the wallet's balance in wallet mode, the credit pot's balance in credits mode. example: '12500' unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Consumption recorded but not yet rolled into a wallet transaction. Always `0` in credits mode, where a consume decrements the real credit pot inside its own transaction and leaves nothing in flight. example: '43.218' available: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `wallet - unsettled` — what the customer can still spend, and the only one of the three to gate on in either mode. Correct the instant a consume commits; in wallet mode it may go negative if they overspent between settlements. example: '12456.782' required: - currency - denomination - wallet - unsettled - available description: >- 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: currency: USD denomination: minor_units wallet: '12500' unsettled: '43.218' available: '12456.782' blocked: type: boolean description: >- Whether the customer's kill switch is on. Consumption is still recorded when it is — blocking is a gate for `check`, not a way to lose ledger entries. example: false policy: type: - object - 'null' properties: markup_percent: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: Percentage added on top of the priced usage. example: '20' floor: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: Balance at or below which the customer is refused. example: '0' required: - markup_percent - floor description: Null when no policy is configured. example: markup_percent: '20' floor: '0' meters: type: - array - 'null' items: type: object properties: key: type: string description: >- The window this meter is for, as the policy names it — `5h`, `7d`, `monthly`. example: 5h included_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: The whole allowance for one instance of this window. example: '50000' used_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Weighted units consumed inside the open instance, counting the call that just returned. Zero when no instance is open. example: '12500' remaining_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `included_units - used_units`, floored at zero. The whole allowance when no instance is open. example: '37500' window_started_at: type: - string - 'null' format: date-time description: >- When the open instance was anchored — the first consumption after the previous instance expired. Null together with `resets_at` when no instance is open. example: '2026-08-20T09:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- When the open instance expires and the allowance comes back in full. Null when no instance is open: nothing has been consumed since the last one ended, so the clock has not started and the next call is what anchors it. example: '2026-08-20T14:14:02.113Z' required: - key - included_units - used_units - remaining_units - window_started_at - resets_at description: >- One rolling allowance window's live state, including the call that just happened. example: key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' description: >- The customer's rolling allowances, in `windows` mode — one entry per window the policy defines, in declaration order, counting the currently open instance. Null in every other mode. This is the live-meters read: poll it to render "37,500 of 50,000 left, resets at 14:14". example: - key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' credits: type: - object - 'null' properties: balance: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Credits left on the pot, at full decimal precision. The same number as `balance.available`. example: '48120.5' currency: type: 'null' description: >- Credits are a count, not money, so they have no currency. Always null — stated rather than omitted so the field does not appear later and change the shape. example: null product_id: type: string description: >- The credit product the pot is keyed by. Credits in Hyperline are one pot per (customer, credit product). example: pro_2f8c1ab4e77d31 low_balance_threshold: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- The pot's own low-balance warning threshold, when one is configured. Independent of the AI policy's `floor`. example: '1000' expiring_soon: type: array items: type: object properties: amount: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Exact decimal string. Interpret the unit using the field description and denomination. example: '5000' expires_at: type: string format: date-time description: >- UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. example: '2026-09-18T00:00:00.000Z' required: - amount - expires_at description: >- Top-ups expiring within 30 days, soonest first, grouped by expiry instant. `amount` is what the top-up granted, not what is left of it — the credit domain only works the unconsumed remainder out at expiry time — so read it as a ceiling on what the customer stands to lose. example: - amount: '5000' expires_at: '2026-09-18T00:00:00Z' rate_card_summary: type: object properties: llm_rows: type: number example: 12 item_rows: type: number example: 4 has_default_llm_row: type: boolean description: >- Whether the card prices models it does not name individually. example: true fallback_credits_per_usd: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Credits per USD for usage the card does not price. Null means such usage is recorded at 0 credits and flagged `price_status: "unpriced"` on its breakdown line, with an `unpriced_usage` warning on the response — it is not billed, and it is not silently treated as free either. example: '1000' required: - llm_rows - item_rows - has_default_llm_row - fallback_credits_per_usd description: >- What the customer's rate card covers, without reprinting it. The card itself is workspace configuration and is not exposed on this endpoint. example: llm_rows: 12 item_rows: 4 has_default_llm_row: true fallback_credits_per_usd: '1000' required: - balance - currency - product_id - low_balance_threshold - expiring_soon - rate_card_summary description: >- The customer's credit pot and rate card. Populated in `credits` mode, null in every other — including a credits-mode policy whose credit product the customer has no balance for, which `check` reports as `credit_pot_missing`. example: balance: '48120.5' currency: null product_id: pro_credits low_balance_threshold: '1000' expiring_soon: - amount: '5000' expires_at: '2026-09-18T00:00:00Z' rate_card_summary: llm_rows: 12 item_rows: 4 has_default_llm_row: true fallback_credits_per_usd: '1000' 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 amounts. 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 this scope is past its boundary RIGHT NOW — the credit pot at or below the floor, or a rolling allowance with no room. It describes the scope's position, not the policy's stance, so it is true under `refuse` as well. example: true unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Overage recorded but not yet settled, in wallet minor units. Non-zero only once a call has actually crossed the boundary under `metered`: a credits or windows call that stayed inside its allowance is settled the instant it is recorded and never enters this number. example: '412.75' required: - currency - mode - active - unsettled description: >- What this scope does when it runs out, and where it stands right now. Null in `wallet` mode, which has no exhaustion boundary — its shadow balance already accrues past zero. `mode: "refuse"` is the default and is today's behaviour: the call that would cross the boundary is refused whole. `mode: "metered"` re-prices that whole call in the overage currency instead and records it as overage. example: currency: USD mode: metered active: true unsettled: '412.75' agents: type: array items: type: object properties: agent: type: string description: >- 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`. example: invoice-copilot 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 amounts. 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: >- The settled source balance — the wallet's balance in wallet mode, the credit pot's balance in credits mode. example: '12500' unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Consumption recorded but not yet rolled into a wallet transaction. Always `0` in credits mode, where a consume decrements the real credit pot inside its own transaction and leaves nothing in flight. example: '43.218' available: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `wallet - unsettled` — what the customer can still spend, and the only one of the three to gate on in either mode. Correct the instant a consume commits; in wallet mode it may go negative if they overspent between settlements. example: '12456.782' required: - currency - denomination - wallet - unsettled - available description: >- 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: currency: USD denomination: minor_units wallet: '12500' unsettled: '43.218' available: '12456.782' blocked: type: boolean description: Whether this agent's own pool is blocked. example: false meters: type: - array - 'null' items: type: object properties: key: type: string description: >- The window this meter is for, as the policy names it — `5h`, `7d`, `monthly`. example: 5h included_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- The whole allowance for one instance of this window. example: '50000' used_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Weighted units consumed inside the open instance, counting the call that just returned. Zero when no instance is open. example: '12500' remaining_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `included_units - used_units`, floored at zero. The whole allowance when no instance is open. example: '37500' window_started_at: type: - string - 'null' format: date-time description: >- When the open instance was anchored — the first consumption after the previous instance expired. Null together with `resets_at` when no instance is open. example: '2026-08-20T09:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- When the open instance expires and the allowance comes back in full. Null when no instance is open: nothing has been consumed since the last one ended, so the clock has not started and the next call is what anchors it. example: '2026-08-20T14:14:02.113Z' required: - key - included_units - used_units - remaining_units - window_started_at - resets_at description: >- One rolling allowance window's live state, including the call that just happened. example: key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' description: >- The customer's rolling allowances, in `windows` mode — one entry per window the policy defines, in declaration order, counting the currently open instance. Null in every other mode. This is the live-meters read: poll it to render "37,500 of 50,000 left, resets at 14:14". example: - key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' 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 amounts. 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 this scope is past its boundary RIGHT NOW — the credit pot at or below the floor, or a rolling allowance with no room. It describes the scope's position, not the policy's stance, so it is true under `refuse` as well. example: true unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Overage recorded but not yet settled, in wallet minor units. Non-zero only once a call has actually crossed the boundary under `metered`: a credits or windows call that stayed inside its allowance is settled the instant it is recorded and never enters this number. example: '412.75' required: - currency - mode - active - unsettled description: >- What this scope does when it runs out, and where it stands right now. Null in `wallet` mode, which has no exhaustion boundary — its shadow balance already accrues past zero. `mode: "refuse"` is the default and is today's behaviour: the call that would cross the boundary is refused whole. `mode: "metered"` re-prices that whole call in the overage currency instead and records it as overage. example: currency: USD mode: metered active: true unsettled: '412.75' required: - agent - mode - balance - blocked - meters - overage description: >- The customer's agents that have a pool of their own, each with its own numbers. Never a total: two pools can be denominated in credits and in weighted allowance units, which have no common unit, so a summed figure across them would mean nothing. Empty when this snapshot was asked about one specific agent. example: - agent: invoice-copilot mode: wallet balance: currency: USD denomination: minor_units wallet: '12500' unsettled: '43.218' available: '12456.782' blocked: false meters: null overage: null required: - agent - mode - balance - blocked - policy - meters - credits - overage - agents '402': description: >- Not enough credits, or a rolling allowance with no room left. Nothing was deducted and no window was incremented. content: application/json: schema: type: object properties: code: type: string enum: - telemetry_managed - not_configured - unsupported_mode - customer_not_found - wallet_missing - credit_pot_missing - pricing_unavailable - insufficient_credits - allowance_exhausted - windows_not_configured description: >- Machine-readable consumption refusal code. - 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. - 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. - pricing_unavailable: Legacy compatibility value; no longer returned. Unpriceable usage is recorded with an unpriced_usage warning. example: not_configured message: type: string description: Human-readable explanation of the refusal. example: This customer has no AI billing policy balance: 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 amounts. 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: >- The settled source balance — the wallet's balance in wallet mode, the credit pot's balance in credits mode. example: '12500' unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Consumption recorded but not yet rolled into a wallet transaction. Always `0` in credits mode, where a consume decrements the real credit pot inside its own transaction and leaves nothing in flight. example: '43.218' available: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `wallet - unsettled` — what the customer can still spend, and the only one of the three to gate on in either mode. Correct the instant a consume commits; in wallet mode it may go negative if they overspent between settlements. example: '12456.782' required: - currency - denomination - wallet - unsettled - available description: >- The balance at the moment of the refusal, when the refusal is about money — `insufficient_credits` and `allowance_exhausted` carry it so an agent knows how short it was without a second round trip. Null otherwise. example: currency: USD denomination: minor_units wallet: '12500' unsettled: '43.218' available: '12456.782' meters: type: - array - 'null' items: type: object properties: key: type: string description: >- The window this meter is for, as the policy names it — `5h`, `7d`, `monthly`. example: 5h included_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: The whole allowance for one instance of this window. example: '50000' used_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Weighted units consumed inside the open instance, counting the call that just returned. Zero when no instance is open. example: '12500' remaining_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `included_units - used_units`, floored at zero. The whole allowance when no instance is open. example: '37500' window_started_at: type: - string - 'null' format: date-time description: >- When the open instance was anchored — the first consumption after the previous instance expired. Null together with `resets_at` when no instance is open. example: '2026-08-20T09:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- When the open instance expires and the allowance comes back in full. Null when no instance is open: nothing has been consumed since the last one ended, so the clock has not started and the next call is what anchors it. example: '2026-08-20T14:14:02.113Z' required: - key - included_units - used_units - remaining_units - window_started_at - resets_at description: >- One rolling allowance window's live state, including the call that just happened. example: key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' description: >- Every window's state at the moment of an `allowance_exhausted` refusal, so the caller can see which one ran out and by how much. Null on every other refusal. example: - key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- The soonest instant one of the windows that blocked the call rolls over — the earliest of them, since that is the next moment the answer could change. Null when no blocking window has an open instance, which means the call is larger than a whole allowance and waiting will not help. Null on every other refusal. example: '2026-08-20T14:14:02.113Z' required: - code - message - balance - meters - resets_at '404': description: Customer not found. content: application/json: schema: type: object properties: code: type: string enum: - telemetry_managed - not_configured - unsupported_mode - customer_not_found - wallet_missing - credit_pot_missing - pricing_unavailable - insufficient_credits - allowance_exhausted - windows_not_configured description: >- Machine-readable consumption refusal code. - 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. - 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. - pricing_unavailable: Legacy compatibility value; no longer returned. Unpriceable usage is recorded with an unpriced_usage warning. example: not_configured message: type: string description: Human-readable explanation of the refusal. example: This customer has no AI billing policy balance: 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 amounts. 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: >- The settled source balance — the wallet's balance in wallet mode, the credit pot's balance in credits mode. example: '12500' unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Consumption recorded but not yet rolled into a wallet transaction. Always `0` in credits mode, where a consume decrements the real credit pot inside its own transaction and leaves nothing in flight. example: '43.218' available: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `wallet - unsettled` — what the customer can still spend, and the only one of the three to gate on in either mode. Correct the instant a consume commits; in wallet mode it may go negative if they overspent between settlements. example: '12456.782' required: - currency - denomination - wallet - unsettled - available description: >- The balance at the moment of the refusal, when the refusal is about money — `insufficient_credits` and `allowance_exhausted` carry it so an agent knows how short it was without a second round trip. Null otherwise. example: currency: USD denomination: minor_units wallet: '12500' unsettled: '43.218' available: '12456.782' meters: type: - array - 'null' items: type: object properties: key: type: string description: >- The window this meter is for, as the policy names it — `5h`, `7d`, `monthly`. example: 5h included_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: The whole allowance for one instance of this window. example: '50000' used_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Weighted units consumed inside the open instance, counting the call that just returned. Zero when no instance is open. example: '12500' remaining_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `included_units - used_units`, floored at zero. The whole allowance when no instance is open. example: '37500' window_started_at: type: - string - 'null' format: date-time description: >- When the open instance was anchored — the first consumption after the previous instance expired. Null together with `resets_at` when no instance is open. example: '2026-08-20T09:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- When the open instance expires and the allowance comes back in full. Null when no instance is open: nothing has been consumed since the last one ended, so the clock has not started and the next call is what anchors it. example: '2026-08-20T14:14:02.113Z' required: - key - included_units - used_units - remaining_units - window_started_at - resets_at description: >- One rolling allowance window's live state, including the call that just happened. example: key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' description: >- Every window's state at the moment of an `allowance_exhausted` refusal, so the caller can see which one ran out and by how much. Null on every other refusal. example: - key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- The soonest instant one of the windows that blocked the call rolls over — the earliest of them, since that is the next moment the answer could change. Null when no blocking window has an open instance, which means the call is larger than a whole allowance and waiting will not help. Null on every other refusal. example: '2026-08-20T14:14:02.113Z' required: - code - message - balance - meters - resets_at '409': description: No billing policy configured. content: application/json: schema: type: object properties: code: type: string enum: - telemetry_managed - not_configured - unsupported_mode - customer_not_found - wallet_missing - credit_pot_missing - pricing_unavailable - insufficient_credits - allowance_exhausted - windows_not_configured description: >- Machine-readable consumption refusal code. - 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. - 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. - pricing_unavailable: Legacy compatibility value; no longer returned. Unpriceable usage is recorded with an unpriced_usage warning. example: not_configured message: type: string description: Human-readable explanation of the refusal. example: This customer has no AI billing policy balance: 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 amounts. 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: >- The settled source balance — the wallet's balance in wallet mode, the credit pot's balance in credits mode. example: '12500' unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Consumption recorded but not yet rolled into a wallet transaction. Always `0` in credits mode, where a consume decrements the real credit pot inside its own transaction and leaves nothing in flight. example: '43.218' available: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `wallet - unsettled` — what the customer can still spend, and the only one of the three to gate on in either mode. Correct the instant a consume commits; in wallet mode it may go negative if they overspent between settlements. example: '12456.782' required: - currency - denomination - wallet - unsettled - available description: >- The balance at the moment of the refusal, when the refusal is about money — `insufficient_credits` and `allowance_exhausted` carry it so an agent knows how short it was without a second round trip. Null otherwise. example: currency: USD denomination: minor_units wallet: '12500' unsettled: '43.218' available: '12456.782' meters: type: - array - 'null' items: type: object properties: key: type: string description: >- The window this meter is for, as the policy names it — `5h`, `7d`, `monthly`. example: 5h included_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: The whole allowance for one instance of this window. example: '50000' used_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Weighted units consumed inside the open instance, counting the call that just returned. Zero when no instance is open. example: '12500' remaining_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `included_units - used_units`, floored at zero. The whole allowance when no instance is open. example: '37500' window_started_at: type: - string - 'null' format: date-time description: >- When the open instance was anchored — the first consumption after the previous instance expired. Null together with `resets_at` when no instance is open. example: '2026-08-20T09:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- When the open instance expires and the allowance comes back in full. Null when no instance is open: nothing has been consumed since the last one ended, so the clock has not started and the next call is what anchors it. example: '2026-08-20T14:14:02.113Z' required: - key - included_units - used_units - remaining_units - window_started_at - resets_at description: >- One rolling allowance window's live state, including the call that just happened. example: key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' description: >- Every window's state at the moment of an `allowance_exhausted` refusal, so the caller can see which one ran out and by how much. Null on every other refusal. example: - key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- The soonest instant one of the windows that blocked the call rolls over — the earliest of them, since that is the next moment the answer could change. Null when no blocking window has an open instance, which means the call is larger than a whole allowance and waiting will not help. Null on every other refusal. example: '2026-08-20T14:14:02.113Z' required: - code - message - balance - meters - resets_at '422': description: >- The policy cannot bill this: an unsupported mode, a missing wallet or credit pot, an unconfigured window card, or usage no rate card prices. content: application/json: schema: type: object properties: code: type: string enum: - telemetry_managed - not_configured - unsupported_mode - customer_not_found - wallet_missing - credit_pot_missing - pricing_unavailable - insufficient_credits - allowance_exhausted - windows_not_configured description: >- Machine-readable consumption refusal code. - 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. - 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. - pricing_unavailable: Legacy compatibility value; no longer returned. Unpriceable usage is recorded with an unpriced_usage warning. example: not_configured message: type: string description: Human-readable explanation of the refusal. example: This customer has no AI billing policy balance: 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 amounts. 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: >- The settled source balance — the wallet's balance in wallet mode, the credit pot's balance in credits mode. example: '12500' unsettled: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Consumption recorded but not yet rolled into a wallet transaction. Always `0` in credits mode, where a consume decrements the real credit pot inside its own transaction and leaves nothing in flight. example: '43.218' available: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `wallet - unsettled` — what the customer can still spend, and the only one of the three to gate on in either mode. Correct the instant a consume commits; in wallet mode it may go negative if they overspent between settlements. example: '12456.782' required: - currency - denomination - wallet - unsettled - available description: >- The balance at the moment of the refusal, when the refusal is about money — `insufficient_credits` and `allowance_exhausted` carry it so an agent knows how short it was without a second round trip. Null otherwise. example: currency: USD denomination: minor_units wallet: '12500' unsettled: '43.218' available: '12456.782' meters: type: - array - 'null' items: type: object properties: key: type: string description: >- The window this meter is for, as the policy names it — `5h`, `7d`, `monthly`. example: 5h included_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: The whole allowance for one instance of this window. example: '50000' used_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Weighted units consumed inside the open instance, counting the call that just returned. Zero when no instance is open. example: '12500' remaining_units: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- `included_units - used_units`, floored at zero. The whole allowance when no instance is open. example: '37500' window_started_at: type: - string - 'null' format: date-time description: >- When the open instance was anchored — the first consumption after the previous instance expired. Null together with `resets_at` when no instance is open. example: '2026-08-20T09:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- When the open instance expires and the allowance comes back in full. Null when no instance is open: nothing has been consumed since the last one ended, so the clock has not started and the next call is what anchors it. example: '2026-08-20T14:14:02.113Z' required: - key - included_units - used_units - remaining_units - window_started_at - resets_at description: >- One rolling allowance window's live state, including the call that just happened. example: key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' description: >- Every window's state at the moment of an `allowance_exhausted` refusal, so the caller can see which one ran out and by how much. Null on every other refusal. example: - key: 5h included_units: '50000' used_units: '12500' remaining_units: '37500' window_started_at: '2026-08-20T09:14:02.113Z' resets_at: '2026-08-20T14:14:02.113Z' resets_at: type: - string - 'null' format: date-time description: >- The soonest instant one of the windows that blocked the call rolls over — the earliest of them, since that is the next moment the answer could change. Null when no blocking window has an open instance, which means the call is larger than a whole allowance and waiting will not help. Null on every other refusal. example: '2026-08-20T14:14:02.113Z' required: - code - message - balance - meters - resets_at 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.