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

# Get billing overview

> **Token scope:** `account` · `org` — read-only tokens allowed.

Billing overview for a window — totals, credits, forecast, per-dimension + per-project breakdown (pure read)



## OpenAPI

````yaml /openapi/org.json get /orgs/{orgId}/billing/overview
openapi: 3.1.0
info:
  title: InstaCloud API — Organization level
  version: 0.1.0
  description: >-
    Endpoints under `/orgs/{orgId}`: members, projects, billing, domains.
    Callable with an account-wide token or a token bound to that organization.


    Generated from the platform's own OpenAPI document
    (https://api.instacloud.com/openapi.json); see the [API
    overview](/reference/api/overview) for authentication and token scopes.
servers:
  - url: https://api.instacloud.com
    description: InstaCloud
security:
  - bearerAuth: []
tags:
  - name: Organization
    description: 'The organization itself: name, members, invitations.'
  - name: Projects
    description: Projects inside an organization.
  - name: Audit
    description: The project's event timeline, including agent-ingested events.
  - name: Domains
    description: >-
      Domains bought through InstaCloud, bring-your-own zones and their DNS
      records.
  - name: Billing
    description: Usage, cycles, invoices and credits.
paths:
  /orgs/{orgId}/billing/overview:
    get:
      tags:
        - Billing
      summary: Get billing overview
      description: >-
        **Token scope:** `account` · `org` — read-only tokens allowed.


        Billing overview for a window — totals, credits, forecast, per-dimension
        + per-project breakdown (pure read)
      operationId: getBillingOverview
      parameters:
        - schema:
            type: integer
          in: query
          name: from
          required: false
          description: unix seconds (default current cycle start)
        - schema:
            type: integer
          in: query
          name: to
          required: false
          description: unix seconds (default current cycle end)
        - schema:
            format: uuid
            type: string
          in: path
          name: orgId
          required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingOverview'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    BillingOverview:
      type: object
      properties:
        window:
          type: object
          properties:
            from:
              type: integer
            to:
              type: integer
        tier:
          type: string
          enum:
            - free
            - pro
            - team
            - enterprise
        billingStatus:
          type: string
          enum:
            - active
            - suspended
        subscriptionStatus:
          type:
            - string
            - 'null'
        totals:
          type: object
          properties:
            usedUsd:
              description: total usage cost in the window
              type: number
            includedUsd:
              description: >-
                tier allowance for the window (free $5 / pro $20 / team $0 — the
                plan fee is flat and usage bills from the first cent /
                enterprise per deal, $0 default); platform-configurable
              type: number
            overageUsd:
              description: >-
                amount still owed for the window: max(0, used − included −
                creditsApplied − (live window ? creditBalance : 0))
              type: number
            creditsUsd:
              description: >-
                remaining included allowance plus the org credit balance (legacy
                merged figure; prefer creditBalanceUsd)
              type: number
            forecastUsd:
              description: linear run-rate projection to the full cycle
              type: number
            creditBalanceUsd:
              description: >-
                credits the org holds as of now (every grant kind, unexpired,
                remaining > 0); not window-scoped; carries over between cycles
              type: number
            creditsAppliedUsd:
              description: >-
                credits taken off this window's billing cycle so far
                (billing_cycles.credit_applied_micros); 0 when the window is not
                a billing cycle
              type: number
        byDimension:
          type: array
          items:
            $ref: '#/components/schemas/DimensionUsage'
        byProject:
          type: array
          items:
            type: object
            properties:
              projectId:
                format: uuid
                type: string
              name:
                type: string
              deletedAt:
                format: date-time
                description: >-
                  when the project was deleted — its usage history outlives it;
                  null for a live project
                type:
                  - string
                  - 'null'
              totalCostUsd:
                type: number
              dimensions:
                type: array
                items:
                  $ref: '#/components/schemas/DimensionUsage'
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    DimensionUsage:
      type: object
      properties:
        dimension:
          type: string
          enum:
            - ram
            - cpu
            - volume
            - storage
            - egress
        quantity:
          type: number
        unit:
          example: GB·min
          type: string
        costUsd:
          description: quantity × unit price for this dimension in the window
          type: number
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Session access JWT or an API token (`insta_<prefix>_<secret>`).

````