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

# IU account snapshot: buckets, forecast, usage by activity and day



## OpenAPI

````yaml /openapi/v3.yaml get /api/v2/billing/iu-usage
openapi: 3.1.0
info:
  title: Semicola Exchange API
  version: 3.0.0-preview
  description: >-
    Platform endpoints of Semicola: sign-in and accounts, members and keys,
    billing, notifications, the Semi assistant (chat stream, confirmations,
    conversations), the MCP App widget host and realtime feeds. Typed agent
    tools live on the MCP server at /mcp/v3.
servers:
  - url: https://api.semicola.com
security:
  - bearerAuth: []
  - sessionCookie: []
tags:
  - name: Auth
  - name: Accounts
  - name: Billing
  - name: Notifications
  - name: Assistant
  - name: Widget host
  - name: Realtime
  - name: Demo
paths:
  /api/v2/billing/iu-usage:
    get:
      tags:
        - Billing
      summary: 'IU account snapshot: buckets, forecast, usage by activity and day'
      operationId: getBillingIuUsage
      parameters:
        - name: cycle
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    anyOf:
                      - type: object
                        properties:
                          cycle:
                            type: string
                          cycleStart:
                            type: string
                            format: date-time
                            pattern: >-
                              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          cycleEnd:
                            type: string
                            format: date-time
                            pattern: >-
                              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          usedIus:
                            type: string
                            pattern: ^-?\d+(\.\d{1,6})?$
                          remainingIus:
                            type: string
                            pattern: ^-?\d+(\.\d{1,6})?$
                          buckets:
                            type: array
                            items:
                              type: object
                              properties:
                                bucket:
                                  type: string
                                  enum:
                                    - free
                                    - rollover
                                    - included
                                    - overage
                                label:
                                  type: string
                                ius:
                                  type: string
                                  pattern: ^-?\d+(\.\d{1,6})?$
                                remaining:
                                  anyOf:
                                    - type: string
                                      pattern: ^-?\d+(\.\d{1,6})?$
                                    - type: 'null'
                              required:
                                - bucket
                                - label
                                - ius
                                - remaining
                              additionalProperties: false
                          overage:
                            type: object
                            properties:
                              ius:
                                type: string
                                pattern: ^-?\d+(\.\d{1,6})?$
                              minor:
                                type: string
                                pattern: ^-?\d+$
                              capMinor:
                                anyOf:
                                  - type: string
                                    pattern: ^-?\d+$
                                  - type: 'null'
                              warnAtMinor:
                                anyOf:
                                  - type: string
                                    pattern: ^-?\d+$
                                  - type: 'null'
                              overWarnThreshold:
                                type: boolean
                              overCap:
                                type: boolean
                            required:
                              - ius
                              - minor
                              - capMinor
                              - warnAtMinor
                              - overWarnThreshold
                              - overCap
                            additionalProperties: false
                          forecast:
                            type: object
                            properties:
                              projectedIusThisCycle:
                                type: string
                                pattern: ^-?\d+(\.\d{1,6})?$
                              projectedOverageMinor:
                                type: string
                                pattern: ^-?\d+$
                            required:
                              - projectedIusThisCycle
                              - projectedOverageMinor
                            additionalProperties: false
                          byActivity:
                            type: array
                            items:
                              type: object
                              properties:
                                activityCode:
                                  type: string
                                displayName:
                                  type: string
                                ius:
                                  type: string
                                  pattern: ^-?\d+(\.\d{1,6})?$
                                count:
                                  type: integer
                                  minimum: 0
                                  maximum: 9007199254740991
                              required:
                                - activityCode
                                - displayName
                                - ius
                                - count
                              additionalProperties: false
                          byDay:
                            type: array
                            items:
                              type: object
                              properties:
                                date:
                                  type: string
                                  pattern: ^\d{4}-\d{2}-\d{2}$
                                ius:
                                  type: string
                                  pattern: ^-?\d+(\.\d{1,6})?$
                              required:
                                - date
                                - ius
                              additionalProperties: false
                          priceList:
                            type: array
                            items:
                              type: object
                              properties:
                                code:
                                  type: string
                                displayName:
                                  type: string
                                ius:
                                  type: string
                                  pattern: ^-?\d+(\.\d{1,6})?$
                                catalogStatus:
                                  type: string
                                  enum:
                                    - PUBLISHED
                                    - CALIBRATING
                                    - MEASURING
                              required:
                                - code
                                - displayName
                                - ius
                                - catalogStatus
                              additionalProperties: false
                          calibrating:
                            type: array
                            items:
                              type: object
                              properties:
                                code:
                                  type: string
                                displayName:
                                  type: string
                                status:
                                  type: string
                                  enum:
                                    - PUBLISHED
                                    - CALIBRATING
                                    - MEASURING
                              required:
                                - code
                                - displayName
                                - status
                              additionalProperties: false
                        required:
                          - cycle
                          - cycleStart
                          - cycleEnd
                          - usedIus
                          - remainingIus
                          - buckets
                          - overage
                          - forecast
                          - byActivity
                          - byDay
                          - priceList
                          - calibrating
                        additionalProperties: false
                      - type: 'null'
                  error:
                    anyOf:
                      - type: object
                        properties:
                          code:
                            type: string
                          message:
                            type: string
                          field:
                            type: string
                          details: {}
                        required:
                          - code
                          - message
                        additionalProperties: false
                      - type: 'null'
                required:
                  - data
                  - error
                additionalProperties: false
        default:
          description: >-
            Error envelope `{data: null, error: {code, message, field?,
            details?}}`.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or OAuth access token.
    sessionCookie:
      type: apiKey
      in: cookie
      name: sc_session

````