> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mountthor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Billing Costs

> Joins live usage against the customer's active price book and
returns itemized line items per (tenant, resource_kind,
resource_class, usage_model). The math is recomputed live on every
request for both the current period and past months. Issued invoices
are served by the invoice routes, not this one.



## OpenAPI

````yaml /api-reference/customer-api.v1.openapi.json get /v1/admin/billing/costs
openapi: 3.1.0
info:
  title: Mount Thor Customer API
  version: v1
servers:
  - description: Mount Thor customer API edge
    url: https://api.mountthor.com
security: []
paths:
  /v1/admin/billing/costs:
    get:
      tags:
        - billing
      summary: List Billing Costs
      description: |-
        Joins live usage against the customer's active price book and
        returns itemized line items per (tenant, resource_kind,
        resource_class, usage_model). The math is recomputed live on every
        request for both the current period and past months. Issued invoices
        are served by the invoice routes, not this one.
      operationId: get_customer_billing_costs
      parameters:
        - description: '`current` or a closed calendar month `YYYY-MM`.'
          in: query
          name: period
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBillingCostsResponse'
          description: Customer-aggregated itemized billing costs
        '400':
          description: Unsupported or malformed period value
        '401':
          description: Missing or invalid bearer credential
        '403':
          description: >-
            Credential is missing billing:read scope, or the human session is
            neither an Administrator nor a billing-owner for this customer
        '409':
          description: Customer has no active contract; cannot derive a price book
        '429':
          content:
            text/plain:
              schema:
                type: string
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds before retry.
              schema:
                minimum: 1
                type: integer
      security:
        - api_key_bearer:
            - billing:read
components:
  schemas:
    CustomerBillingCostsResponse:
      additionalProperties: false
      description: Customer-level itemized cost response.
      properties:
        currency:
          description: |-
            ISO 4217 currency code; today always `USD` per umbrella
            scoping decision.
          example: USD
          type: string
        customer_id:
          description: Stable UUID for the customer account.
          type: string
        line_items:
          description: |-
            Itemized line items, ordered by (tenant_slug, resource_kind,
            resource_class, usage_model) for stable client rendering.
          items:
            $ref: '#/components/schemas/BillingCostLineItem'
          type: array
        period:
          $ref: '#/components/schemas/BillingCostsPeriod'
          description: Window covered by the response.
        total_cents:
          description: Customer total = sum of `amount_cents` across all line items.
          format: int64
          type: integer
      required:
        - customer_id
        - currency
        - period
        - line_items
        - total_cents
      type: object
    BillingCostLineItem:
      additionalProperties: false
      description: |-
        A single itemized cost line. Quantity is in seconds (the umbrella
        unit for compute lifecycles); unit_price_cents is denominated in
        `unit` (per-second or per-hour) from the active price book item.
        Per-second: amount_cents = quantity_seconds * unit_price_cents.
        Per-hour: amount_cents = quantity_seconds * unit_price_cents / 3600,
        truncated toward zero (sub-cent remainders drop in the customer's
        favor).
      properties:
        amount_cents:
          description: |-
            Computed line amount: `quantity_seconds * unit_price_cents` for
            per-second items; `quantity_seconds * unit_price_cents / 3600`
            (truncated toward zero) for per-hour items.
          format: int64
          type: integer
        priced:
          type: boolean
        quantity_seconds:
          description: |-
            Billable seconds aggregated for this line. Closed lifecycles
            have per-class minimums applied; open lifecycles report
            elapsed raw time.
          format: int64
          type: integer
        resource_class:
          description: Resource class string (e.g. `mac-m4-pro`).
          example: mac-m4-pro
          type: string
        resource_kind:
          description: '`bare_metal_machine` or `vm`.'
          example: bare_metal_machine
          type: string
        tenant_id:
          description: Stable UUID for the tenant whose usage this line attributes.
          example: 22222222-2222-2222-2222-222222222222
          type: string
        tenant_slug:
          description: Human-readable tenant slug.
          example: acme-prod
          type: string
        unit:
          example: hour
          type: string
        unit_price_cents:
          description: |-
            Unit price from the customer's active price book, denominated
            in `unit`. 0 for the alpha SKU (`alpha-2026`).
          format: int64
          type: integer
        usage_model:
          example: reserved
          type: string
      required:
        - tenant_id
        - tenant_slug
        - resource_kind
        - resource_class
        - usage_model
        - quantity_seconds
        - unit_price_cents
        - unit
        - amount_cents
        - priced
      type: object
    BillingCostsPeriod:
      additionalProperties: false
      description: Closed-period or current-month window the costs response covers.
      properties:
        end:
          description: Exclusive end of the costs window.
          example: '2026-06-04T00:00:00Z'
          type: string
        requested:
          description: |-
            `current` when computed live for the current month; otherwise
            the requested `YYYY-MM` value.
          example: current
          type: string
        start:
          description: Inclusive start of the costs window.
          example: '2026-06-01T00:00:00Z'
          type: string
      required:
        - start
        - end
        - requested
      type: object
  securitySchemes:
    api_key_bearer:
      bearerFormat: mthr_live_*
      description: Bearer scheme name used by typed customer admin operations.
      scheme: bearer
      type: http

````