> ## 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 billing overview > Everything the customer's AI billing page renders in one read: the customer, their default policy, and one row per agent with a pool of its own — each with its balance, mode and consumed total. Consumed totals come from the billed ledger, never from provider cost. ## OpenAPI ````yaml get /v1/ai/billing/customers/{customer_id}/overview 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}/overview: get: tags: - AI > Billing summary: Get a customer's agent billing overview description: >- Everything the customer's AI billing page renders in one read: the customer, their default policy, and one row per agent with a pool of its own — each with its balance, mode and consumed total. Consumed totals come from the billed ledger, never from provider cost. operationId: getAgentCustomerOverview parameters: - schema: type: string required: true name: customer_id in: path responses: '200': description: '' content: application/json: schema: type: object properties: customer: type: object properties: id: type: string description: Unique Hyperline identifier for this resource. example: d18603dd-7285-4bf5-a45e-88d7de8f37c9 name: type: string description: Human-readable resource name. example: Support agent plan external_id: type: - string - 'null' description: >- Customer identifier supplied by your application, or null. example: customer_123 domain: type: - string - 'null' pattern: >- ^(?!:\/\/)(?=.{1,253}$)(?!-)([a-z0-9-]{1,63}\.)+[a-z]{2,63}$ description: Customer domain without a URL scheme. example: acme.com status: type: string enum: - active - archived description: |- Customer lifecycle status. - active: Customer is active. - archived: Customer is archived. example: active country: type: - string - 'null' enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BF - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ES-CE - ES-ML - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - IC - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PT-20 - PT-30 - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - XK - YE - YT - ZA - ZM - ZW description: Supported country code for the customer. example: FR 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 required: - id - name - external_id - domain - status - country - currency description: Customer summary for this billing overview. example: id: cus_example name: Acme external_id: customer_123 domain: acme.com status: active country: FR currency: USD default_policy: type: - object - 'null' properties: id: type: string description: Unique Hyperline identifier for this resource. example: d18603dd-7285-4bf5-a45e-88d7de8f37c9 customer_id: type: string description: Hyperline customer identifier. example: cus_example agent_slug: type: - string - 'null' description: >- Agent scope identifier. Null is the customer's shared pool. example: support is_default: type: boolean description: >- Whether this is the default plan or shared customer scope. example: false 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 wallet_id: type: - string - 'null' description: >- Customer wallet identifier. Omit on wallet policy writes to provision or reuse the customer's wallet. example: wal_example credit_product_id: type: - string - 'null' description: >- Public credit product identifier whose balance this policy consumes. example: prd_credits 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' overage_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 overage_markup_percent: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id. example: '10' overage_rate_card_id: type: - string - 'null' description: >- Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup. example: airc_overage overage_rate_card_source: type: - string - 'null' enum: - policy - plan description: >- Source of the effective overage rate card. Null when no card is configured. - policy: Selected directly on the customer policy. - plan: Inherited from the attached plan. example: plan overage_wallet_id: type: - string - 'null' description: >- Wallet charged for overage. Null bills overage in arrears. example: wal_example floor: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Minimum available balance a spend check requires, in the policy's denomination. example: '0' credit_rates: type: - object - 'null' properties: llm: type: array items: type: object properties: provider: type: string minLength: 1 maxLength: 64 description: >- AI model provider, or the vendor of a custom cost item. This is not an integration connection. example: anthropic model: type: string minLength: 1 maxLength: 128 description: >- Model identifier, or custom item identifier. Null on wildcard pricing rows. example: claude-sonnet-5 credits_per_1m_input: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per million input tokens, as an exact decimal string. example: '1000' credits_per_1m_output: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per million output tokens, as an exact decimal string. example: '5000' credits_per_1m_cached_input: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per million cached input tokens, as an exact decimal string. example: '100' credits_per_1m_cache_write: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per million cache write tokens, as an exact decimal string. example: '1250' dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per maxItems: 20 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - credits_per_1m_input - credits_per_1m_output maxItems: 500 description: >- Token pricing rows, matched by provider and model specificity. example: [] items: type: array items: type: object properties: vendor: type: string minLength: 1 maxLength: 64 description: >- Vendor identifier matching the custom item usage payload. example: search item: type: string minLength: 1 maxLength: 128 description: Custom item name matching the usage payload. example: search credits_per_unit: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per item unit, as an exact decimal string. example: '10' dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per maxItems: 20 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - vendor - item - credits_per_unit maxItems: 500 description: Per-item pricing rows. example: [] fallback_credits_per_usd: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per USD of unmatched provider cost. Omission leaves unmatched usage unpriced. example: '1000' description: >- Inline credit pricing. Mutually exclusive with rate_card_id. Omitted rates may be supplied by a plan or product default. example: fallback_credits_per_usd: '1000' window_rates: type: - object - 'null' properties: unit_rates: type: object properties: llm: type: array items: type: object properties: provider: type: string minLength: 1 maxLength: 64 description: >- AI model provider, or the vendor of a custom cost item. This is not an integration connection. example: anthropic model: type: string minLength: 1 maxLength: 128 description: >- Model identifier, or custom item identifier. Null on wildcard pricing rows. example: claude-sonnet-5 units_per_1m_input: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per million input tokens, as an exact decimal string. example: '1000' units_per_1m_output: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per million output tokens, as an exact decimal string. example: '5000' units_per_1m_cached_input: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per million cached input tokens, as an exact decimal string. example: '100' units_per_1m_cache_write: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per million cache write tokens, as an exact decimal string. example: '1250' dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per maxItems: 20 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - units_per_1m_input - units_per_1m_output maxItems: 500 description: >- Token pricing rows, matched by provider and model specificity. example: [] items: type: array items: type: object properties: vendor: type: string minLength: 1 maxLength: 64 description: >- Vendor identifier matching the custom item usage payload. example: search item: type: string minLength: 1 maxLength: 128 description: >- Custom item name matching the usage payload. example: search units_per_unit: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per item unit, as an exact decimal string. example: '10' dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per maxItems: 20 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - vendor - item - units_per_unit maxItems: 500 description: Per-item pricing rows. example: [] fallback_units_per_usd: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Allowance units charged per USD of unmatched provider cost. Omission leaves unmatched usage unpriced. example: '1000' description: >- Conversion from token and item usage to weighted allowance units. example: fallback_units_per_usd: '1000' windows: type: array items: type: object properties: key: type: string minLength: 1 maxLength: 32 pattern: ^[a-z0-9][a-z0-9_-]*$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens duration_minutes: type: integer minimum: 1 maximum: 527040 description: >- Rolling allowance duration in whole minutes, from 1 through 527040. example: 1440 included_units: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Weighted units included in one allowance window, as an exact decimal string. example: '10000' required: - key - duration_minutes - included_units minItems: 1 maxItems: 8 description: >- Rolling allowances. Required for windows plans; each window meters every call. A plan replacement replaces the entire array. example: - key: daily duration_minutes: 1440 included_units: '10000' required: - unit_rates - windows description: >- Window definitions and optional inline unit rates. An attached plan may supply omitted definitions; rate_card_id may supply unit rates. example: unit_rates: fallback_units_per_usd: '1000' windows: - key: daily duration_minutes: 1440 included_units: '10000' rate_card_id: type: - string - 'null' description: >- Rate card reference. On policy writes, omission preserves the current reference and null detaches it; on plan replacement omission clears it. example: airc_example rate_card_source: type: - string - 'null' enum: - policy - plan description: >- Source of the effective rate card. Null when no card is configured. - policy: Selected directly on the customer policy. - plan: Inherited from the attached plan. example: policy plan: type: - object - 'null' properties: id: type: string description: Unique Hyperline identifier for this resource. example: aiplan_example name: type: string description: Human-readable resource name. example: Support agent plan required: - id - name description: Attached plan summary, or null. example: id: aiplan_example name: Support agent plan settlement_interval_minutes: type: - number - 'null' description: >- Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule. example: 60 settlement_schedule: type: - string - 'null' enum: - calendar_month description: >- Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes. - calendar_month: Settles at the end of each UTC calendar month. example: calendar_month resolved_rate_card: type: - object - 'null' properties: fallback_per_usd: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Credits, allowance units, or major currency units per USD of provider cost. Null leaves unmatched usage unpriced. example: '1' layer_count: type: number description: >- Number of pricing sources contributing to the effective card. example: 1 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 required: - fallback_per_usd - layer_count - llm_rows - item_rows - has_default_llm_row description: >- Summary of the effective pricing after applying rate-card inheritance. Null when no card resolves. example: fallback_per_usd: '1000' layer_count: 1 llm_rows: 1 item_rows: 0 has_default_llm_row: true blocked: type: boolean description: Whether spending is disabled for this billing scope. example: false created_at: type: string format: date-time description: Creation time as a UTC ISO 8601 timestamp. example: '2026-09-01T00:00:00Z' updated_at: type: string format: date-time description: Last update time as a UTC ISO 8601 timestamp. example: '2026-09-02T12:00:00Z' required: - id - customer_id - agent_slug - is_default - mode - wallet_id - credit_product_id - markup_percent - overage_mode - overage_markup_percent - overage_rate_card_id - overage_rate_card_source - overage_wallet_id - floor - credit_rates - window_rates - rate_card_id - rate_card_source - plan - settlement_interval_minutes - settlement_schedule - resolved_rate_card - blocked - created_at - updated_at description: >- Policy for the customer shared pool, or null when unconfigured. example: null 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 display_name: type: string description: Human-readable agent name. example: Support agent has_override: type: boolean description: Whether this agent has a billing policy of its own. example: false policy: type: - object - 'null' properties: id: type: string description: Unique Hyperline identifier for this resource. example: d18603dd-7285-4bf5-a45e-88d7de8f37c9 customer_id: type: string description: Hyperline customer identifier. example: cus_example agent_slug: type: - string - 'null' description: >- Agent scope identifier. Null is the customer's shared pool. example: support is_default: type: boolean description: >- Whether this is the default plan or shared customer scope. example: false 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 wallet_id: type: - string - 'null' description: >- Customer wallet identifier. Omit on wallet policy writes to provision or reuse the customer's wallet. example: wal_example credit_product_id: type: - string - 'null' description: >- Public credit product identifier whose balance this policy consumes. example: prd_credits 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' overage_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 overage_markup_percent: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id. example: '10' overage_rate_card_id: type: - string - 'null' description: >- Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup. example: airc_overage overage_rate_card_source: type: - string - 'null' enum: - policy - plan description: >- Source of the effective overage rate card. Null when no card is configured. - policy: Selected directly on the customer policy. - plan: Inherited from the attached plan. example: plan overage_wallet_id: type: - string - 'null' description: >- Wallet charged for overage. Null bills overage in arrears. example: wal_example floor: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Minimum available balance a spend check requires, in the policy's denomination. example: '0' credit_rates: type: - object - 'null' properties: llm: type: array items: type: object properties: provider: type: string minLength: 1 maxLength: 64 description: >- AI model provider, or the vendor of a custom cost item. This is not an integration connection. example: anthropic model: type: string minLength: 1 maxLength: 128 description: >- Model identifier, or custom item identifier. Null on wildcard pricing rows. example: claude-sonnet-5 credits_per_1m_input: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per million input tokens, as an exact decimal string. example: '1000' credits_per_1m_output: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per million output tokens, as an exact decimal string. example: '5000' credits_per_1m_cached_input: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per million cached input tokens, as an exact decimal string. example: '100' credits_per_1m_cache_write: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per million cache write tokens, as an exact decimal string. example: '1250' dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per maxItems: 20 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - credits_per_1m_input - credits_per_1m_output maxItems: 500 description: >- Token pricing rows, matched by provider and model specificity. example: [] items: type: array items: type: object properties: vendor: type: string minLength: 1 maxLength: 64 description: >- Vendor identifier matching the custom item usage payload. example: search item: type: string minLength: 1 maxLength: 128 description: >- Custom item name matching the usage payload. example: search credits_per_unit: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per item unit, as an exact decimal string. example: '10' dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per maxItems: 20 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - vendor - item - credits_per_unit maxItems: 500 description: Per-item pricing rows. example: [] fallback_credits_per_usd: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Credits charged per USD of unmatched provider cost. Omission leaves unmatched usage unpriced. example: '1000' description: >- Inline credit pricing. Mutually exclusive with rate_card_id. Omitted rates may be supplied by a plan or product default. example: fallback_credits_per_usd: '1000' window_rates: type: - object - 'null' properties: unit_rates: type: object properties: llm: type: array items: type: object properties: provider: type: string minLength: 1 maxLength: 64 description: >- AI model provider, or the vendor of a custom cost item. This is not an integration connection. example: anthropic model: type: string minLength: 1 maxLength: 128 description: >- Model identifier, or custom item identifier. Null on wildcard pricing rows. example: claude-sonnet-5 units_per_1m_input: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per million input tokens, as an exact decimal string. example: '1000' units_per_1m_output: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per million output tokens, as an exact decimal string. example: '5000' units_per_1m_cached_input: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per million cached input tokens, as an exact decimal string. example: '100' units_per_1m_cache_write: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per million cache write tokens, as an exact decimal string. example: '1250' dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per maxItems: 20 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - units_per_1m_input - units_per_1m_output maxItems: 500 description: >- Token pricing rows, matched by provider and model specificity. example: [] items: type: array items: type: object properties: vendor: type: string minLength: 1 maxLength: 64 description: >- Vendor identifier matching the custom item usage payload. example: search item: type: string minLength: 1 maxLength: 128 description: >- Custom item name matching the usage payload. example: search units_per_unit: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Units charged per item unit, as an exact decimal string. example: '10' dimensions: type: array items: type: object properties: key: type: string pattern: ^[a-z0-9_.]{1,64}$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens rate: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Applied rate. Receipt lines may contain a human-readable rate expression. example: '3' per: type: string enum: - 1m - 1k - unit description: |- Quantity basis for the dimension rate. - 1m: Per million units. - 1k: Per thousand units. - unit: Per single unit. example: 1m required: - key - rate - per maxItems: 20 description: >- Additional billable dimensions; each key matches a usage_extra key and rates use the owning card's units or USD for cost-catalog dimensions. example: - key: cached_input_tokens rate: '0.3' per: 1m required: - vendor - item - units_per_unit maxItems: 500 description: Per-item pricing rows. example: [] fallback_units_per_usd: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Allowance units charged per USD of unmatched provider cost. Omission leaves unmatched usage unpriced. example: '1000' description: >- Conversion from token and item usage to weighted allowance units. example: fallback_units_per_usd: '1000' windows: type: array items: type: object properties: key: type: string minLength: 1 maxLength: 32 pattern: ^[a-z0-9][a-z0-9_-]*$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens duration_minutes: type: integer minimum: 1 maximum: 527040 description: >- Rolling allowance duration in whole minutes, from 1 through 527040. example: 1440 included_units: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Weighted units included in one allowance window, as an exact decimal string. example: '10000' required: - key - duration_minutes - included_units minItems: 1 maxItems: 8 description: >- Rolling allowances. Required for windows plans; each window meters every call. A plan replacement replaces the entire array. example: - key: daily duration_minutes: 1440 included_units: '10000' required: - unit_rates - windows description: >- Window definitions and optional inline unit rates. An attached plan may supply omitted definitions; rate_card_id may supply unit rates. example: unit_rates: fallback_units_per_usd: '1000' windows: - key: daily duration_minutes: 1440 included_units: '10000' rate_card_id: type: - string - 'null' description: >- Rate card reference. On policy writes, omission preserves the current reference and null detaches it; on plan replacement omission clears it. example: airc_example rate_card_source: type: - string - 'null' enum: - policy - plan description: >- Source of the effective rate card. Null when no card is configured. - policy: Selected directly on the customer policy. - plan: Inherited from the attached plan. example: policy plan: type: - object - 'null' properties: id: type: string description: >- Unique Hyperline identifier for this resource. example: aiplan_example name: type: string description: Human-readable resource name. example: Support agent plan required: - id - name description: Attached plan summary, or null. example: id: aiplan_example name: Support agent plan settlement_interval_minutes: type: - number - 'null' description: >- Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule. example: 60 settlement_schedule: type: - string - 'null' enum: - calendar_month description: >- Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes. - calendar_month: Settles at the end of each UTC calendar month. example: calendar_month resolved_rate_card: type: - object - 'null' properties: fallback_per_usd: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Credits, allowance units, or major currency units per USD of provider cost. Null leaves unmatched usage unpriced. example: '1' layer_count: type: number description: >- Number of pricing sources contributing to the effective card. example: 1 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 required: - fallback_per_usd - layer_count - llm_rows - item_rows - has_default_llm_row description: >- Summary of the effective pricing after applying rate-card inheritance. Null when no card resolves. example: fallback_per_usd: '1000' layer_count: 1 llm_rows: 1 item_rows: 0 has_default_llm_row: true blocked: type: boolean description: >- Whether spending is disabled for this billing scope. example: false created_at: type: string format: date-time description: Creation time as a UTC ISO 8601 timestamp. example: '2026-09-01T00:00:00Z' updated_at: type: string format: date-time description: Last update time as a UTC ISO 8601 timestamp. example: '2026-09-02T12:00:00Z' required: - id - customer_id - agent_slug - is_default - mode - wallet_id - credit_product_id - markup_percent - overage_mode - overage_markup_percent - overage_rate_card_id - overage_rate_card_source - overage_wallet_id - floor - credit_rates - window_rates - rate_card_id - rate_card_source - plan - settlement_interval_minutes - settlement_schedule - resolved_rate_card - blocked - created_at - updated_at description: >- Billing rules resolved for this scope, or null when unconfigured. example: null 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 blocked: type: boolean description: Whether spending is disabled for this billing scope. example: false 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 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' 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 consumed: 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 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 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' entry_count: type: number description: >- Number of consumption entries included in this total. example: 1 required: - currency - denomination - amount - entry_count description: >- Consumption total in one denomination and currency. Null when no comparable total exists, including mixed currencies. example: currency: USD denomination: minor_units amount: '1250' entry_count: 100 unpriced_entry_count: type: number description: >- Number of entries containing at least one unpriced line. example: 0 last_consumed_at: type: - string - 'null' format: date-time description: >- Last consumed at, as a UTC ISO 8601 timestamp. Null when unavailable. example: '2026-09-02T12:00:00Z' required: - agent - display_name - has_override - policy - mode - blocked - balance - meters - credits - consumed - unpriced_entry_count - last_consumed_at description: Agent scopes with their own policy or consumption history. example: [] unpriced_entry_count: type: number description: Number of entries containing at least one unpriced line. example: 0 required: - customer - default_policy - agents - unpriced_entry_count '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.