---
title: "Get Operator Economics"
method: GET
path: "/api/v1/internal/economics/"
tags: ["internal", "internal-economics"]
---

# Get Operator Economics

`GET /api/v1/internal/economics/`

Revenue, usage, direct cost and margin for every billing account.

## Response `200`

Successful Response

- OperatorEconomicsResponse
  - `as_of` string, date-time, required
  - `rows` EconomicsRowResponse[], required
    - `workspace_id` string, uuid, required
    - `workspace_name` string, required
    - `workspace_type` 'standard' | 'discovery', required
    - `plan_key` string, required
    - `status` 'pending' | 'active' | 'past_due' | 'unpaid' | 'cancelled', required — Subscription state as MAIA understands it, not as Stripe reports it. ``PAST_DUE`` is the retry window: full access with a visible warning. ``UNPAID`` is that window exhausted — paid work refuses until payment succeeds, but the subscription has not ended, so purchased usage is kept. ``CANCELLED`` is paid access ended; only this transition expires it.
    - `is_free` boolean, required
    - `period_start` string, date, required
    - `period_end` string, date, required
    - `stripe_customer_url` string, nullable, required
    - `period` PeriodEconomicsResponse, required
      - `subscription_fee_usd` string, nullable, required
      - `reload_usd` string, required
      - `revenue` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `customer_usage_usd` string, required
      - `direct_cost` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cash_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `rate_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cost_by_category` object, required
      - `cost_by_spend_class` object, required
    - `lifetime` LifetimeEconomicsResponse, required
      - `reload_usd` string, required
      - `customer_usage_usd` string, required
      - `direct_cost` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `rate_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cost_by_category` object, required
      - `cost_by_spend_class` object, required
    - `allowance` AllowancePositionResponse, required
      - `cap_usd` string, nullable, required
      - `remaining_usd` string, nullable, required
      - `consumed_usd` string, required
    - `paid_balance` PaidBalancePositionResponse, required
      - `included_remaining_usd` string, required
      - `purchased_balance_usd` string, required
    - `reloads` ReloadFactsResponse, required
      - `period_attempt_count` integer, required
      - `last_status` 'pending' | 'requires_action' | 'succeeded' | 'failed' | 'canceled', required — Where one attempt stands, as read back from its PaymentIntent.
      - `last_failure_code` 'authentication_required' | 'card_declined' | 'no_saved_payment_method' | 'not_charged' | 'payment_failed', required — Why an attempt ended without collecting, in customer-actionable terms.
      - `last_attempted_at` string, date-time, nullable, required
      - `last_amount_usd` string, nullable, required
      - `unconfirmed_payment_count` integer, required
    - `drift` BucketDriftResponse[], required
      - `bucket` 'included' | 'given' | 'purchased', required — Which funding source an entry moved. Usage staff give is its own bucket rather than a part of the purchased one. Both are spendable at once and both expire when paid access ends, but only purchased usage is dollars the customer bought, and a customer is told dollars only for those. A bucket keeps that split on the ledger, where the reconciliation sweep can rebuild it; a column beside the purchased balance could only be believed.
      - `stored_usd` string, required
      - `ledger_usd` string, required
      - `difference_usd` string, required
  - `portfolio_total` EconomicsTotalsResponse, required
    - `row_count` integer, required
    - `period` PeriodEconomicsResponse, required
      - `subscription_fee_usd` string, nullable, required
      - `reload_usd` string, required
      - `revenue` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `customer_usage_usd` string, required
      - `direct_cost` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cash_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `rate_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cost_by_category` object, required
      - `cost_by_spend_class` object, required
    - `lifetime` LifetimeEconomicsResponse, required
      - `reload_usd` string, required
      - `customer_usage_usd` string, required
      - `direct_cost` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `rate_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cost_by_category` object, required
      - `cost_by_spend_class` object, required
  - `free_tier_subtotal` EconomicsTotalsResponse, required
    - `row_count` integer, required
    - `period` PeriodEconomicsResponse, required
      - `subscription_fee_usd` string, nullable, required
      - `reload_usd` string, required
      - `revenue` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `customer_usage_usd` string, required
      - `direct_cost` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cash_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `rate_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cost_by_category` object, required
      - `cost_by_spend_class` object, required
    - `lifetime` LifetimeEconomicsResponse, required
      - `reload_usd` string, required
      - `customer_usage_usd` string, required
      - `direct_cost` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `rate_margin` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
        - `known_usd` string, required
        - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
      - `cost_by_category` object, required
      - `cost_by_spend_class` object, required
  - `discovery_spend` DiscoverySpendLineResponse, required
    - `spend` MoneyFigureResponse, required — ``known_usd`` is the priced part; ``bound`` says where the real amount lies.
      - `known_usd` string, required
      - `bound` 'exact' | 'at_least' | 'at_most' | 'unknown', required — Where the real amount lies relative to a figure's ``known_usd``.
    - `next_alert_usd` string, required

## Changes

- **2026-09-19** `924eeadc29ad` — 1 breaking, 1 info
  - removed the required property `rows/items/origin` from the response with the `200` status
  - added the required property `rows/items/workspace_type` to the response with the `200` status
- **2026-09-19** `8fb358001d37` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/internal/economics/get.md)

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/maia-analytics/apis/maia-api/revisions/924eeadc29ad?raw)