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

# Get organization usage

> Fetch your organization's current usage against its plan allocation.

<Warning>
  This is a beta endpoint currently under active development. We're working to stabilize the API and will minimize breaking changes wherever possible, but they may still occur as we refine the interface.

  For production support or migration assistance, reach out at <a href="mailto:hello@allium.so">[hello@allium.so](mailto:hello@allium.so)</a>.
</Warning>

<Info>
  Only available to organizations on an **Allium Subscription** or **\[Free
  Trial] Allium Subscription** plan.
</Info>

Returns your organization's included and consumed Explorer and Developer units for the current allocation period.

For a visual breakdown by endpoint, user, source, and more, see [Usage & Billing](/app/organization-management/usage-and-billing) in the Allium app.

## Billing period vs. allocation period

Billing period is always monthly, but your organization's included allocation may be on a different cadence.

* **Monthly allocation**: Allocation and billing periods will be the same.
* **Annual allocation**: Allocation period spans a year. `consumed_amounts` is the cumulative total across that year.

## Trial organizations

For organizations on trial without a periodic allocation, the allocation fields can be ignored. `consumed_amounts` reports current billing period usage.

## Legacy credits plans

For organizations on Allium's earlier credits-based plan, the response uses `credits` instead of `explorer_units` and `developer_units`:

```json theme={null}
{
  "allocation_amounts": { "credits": 10000 },
  "consumed_amounts": { "credits": 4321.5 }
}
```


## OpenAPI

````yaml /_openapi/account-api.json GET /api/v1/account/organization/usage
openapi: 3.1.0
info:
  title: Allium Account API
  version: 0.1.0
servers:
  - url: https://api.allium.so
security: []
paths:
  /api/v1/account/organization/usage:
    get:
      tags:
        - ACCOUNT
      summary: Get organization usage
      operationId: get_organization_usage_api_v1_account_organization_usage_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationUsageSummary'
              examples:
                explorer_developer_units:
                  summary: Explorer and developer units
                  value:
                    billing_period_start: '2026-04-01T00:00:00Z'
                    billing_period_end: '2026-05-01T00:00:00Z'
                    allocation_period_start: '2026-04-01T00:00:00Z'
                    allocation_period_end: '2026-05-01T00:00:00Z'
                    allocation_cadence: monthly
                    allocation_amounts:
                      explorer_units: 100
                      developer_units: 2000000
                    consumed_amounts:
                      explorer_units: 12.5
                      developer_units: 341523
                legacy_credits:
                  summary: Legacy credits
                  value:
                    billing_period_start: '2026-04-01T00:00:00Z'
                    billing_period_end: '2026-05-01T00:00:00Z'
                    allocation_period_start: '2026-01-01T00:00:00Z'
                    allocation_period_end: '2027-01-01T00:00:00Z'
                    allocation_cadence: annual
                    allocation_amounts:
                      credits: 10000
                    consumed_amounts:
                      credits: 4321.5
      security:
        - APIKeyBearer: []
components:
  schemas:
    OrganizationUsageSummary:
      type: object
      title: OrganizationUsageSummary
      required:
        - billing_period_start
        - billing_period_end
        - allocation_period_start
        - allocation_period_end
        - allocation_cadence
        - allocation_amounts
        - consumed_amounts
      properties:
        billing_period_start:
          type: string
          format: date-time
        billing_period_end:
          type: string
          format: date-time
        allocation_period_start:
          type: string
          format: date-time
          nullable: true
        allocation_period_end:
          type: string
          format: date-time
          nullable: true
        allocation_cadence:
          anyOf:
            - type: string
              enum:
                - monthly
                - annual
            - type: 'null'
        allocation_amounts:
          anyOf:
            - $ref: '#/components/schemas/ExplorerDeveloperUnitAmounts'
            - $ref: '#/components/schemas/CreditsAmounts'
          description: >-
            Shape depends on plan type: explorer/developer unit plans return
            `explorer_units` and `developer_units`; legacy plans return
            `credits`.
        consumed_amounts:
          anyOf:
            - $ref: '#/components/schemas/ExplorerDeveloperUnitUsageAmounts'
            - $ref: '#/components/schemas/CreditsUsageAmounts'
          description: Shape mirrors `allocation_amounts`.
    ExplorerDeveloperUnitAmounts:
      type: object
      title: ExplorerDeveloperUnitAmounts
      properties:
        explorer_units:
          type: integer
          default: 0
        developer_units:
          type: integer
          default: 0
    CreditsAmounts:
      type: object
      title: CreditsAmounts
      properties:
        credits:
          type: integer
          default: 0
    ExplorerDeveloperUnitUsageAmounts:
      type: object
      title: ExplorerDeveloperUnitUsageAmounts
      properties:
        explorer_units:
          type: number
          format: float
          default: 0
        developer_units:
          type: number
          format: float
          default: 0
    CreditsUsageAmounts:
      type: object
      title: CreditsUsageAmounts
      properties:
        credits:
          type: number
          format: float
          default: 0
  securitySchemes:
    APIKeyBearer:
      type: apiKey
      in: header
      name: X-API-KEY

````