---
title: "Posted P&L expense breakdown over completed months"
method: GET
path: "/companies/{companyId}/metrics/expense-breakdown"
tags: ["Overview"]
---

# Posted P&L expense breakdown over completed months

`GET /companies/{companyId}/metrics/expense-breakdown`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/companies/{companyId}/metrics/expense-breakdown`
- Auth: HTTP bearer

Home "Expenses by category" card (F18). Signed net posted expense activity per category over a server-resolved completed-month window (never the current partial month), covering every P&L expense family (COGS, operating expense, depreciation/amortization, interest, income tax, other expense) with signed contra/refund effects. Exact minor-unit strings. A zero or negative signed total returns rows and total without percentages; a window the posted-books month census does not fully cover, mixed-currency, truncated, or entity-unattributable coverage returns available:false with a reason (never a partial total).

## Query parameters

- `entityId` string, uuid, required
- `months` 1 | 3 | 6 | 12, required
- `live` 'true' | 'false'

## Response `200`

Expense-breakdown metric envelope

- ExpenseBreakdownResponse
  - `success` true, required
  - `data` ExpenseBreakdownMetric, required: Availability envelope. available:true carries value; available:false carries reason (insufficient_history, mixed_currency, incomplete_provenance, entity_scope_unavailable, truncated, failed) and never a numeric value. available:true additionally asserts that the posted-books month census covers EVERY window month: a window whose books start mid-range (or carry a mid-history gap) is insufficient_history with a missingMonths diagnostic, never a partial total captioned across months it does not cover.
    - `available` boolean, required
    - `reason` string
    - `diagnostic` object: Present on the insufficient_history census failure.
      - `missingMonths` string[]: Window months with no posted-books evidence.
    - `authority` object, required
      - `companyId` string, uuid, required
      - `entityId` string, uuid, required
      - `basis` 'posted_pnl_expense_breakdown', required
      - `asOf` string, required
      - `startMonth` string
      - `endMonth` string
      - `monthKeys` string[]
      - `postedThrough` string, date: Live reads only (live=true). endMonth is the month in progress and its figures run to this date.
    - `completeness` MetricCompleteness, required: Coverage assertion for a per-metric value/authority contract. An available metric carries all three booleans as true.
      - `windowComplete` boolean, required
      - `sourceComplete` boolean, required
      - `provenanceComplete` boolean, required
      - `historyCompleteFrom` string
      - `booksAsOf` string
      - `sourceGeneration` string
    - `value` object
      - `percentageStatus` 'available' | 'unavailable_non_positive' | 'unavailable_offsetting_rows', required: unavailable_non_positive when the signed total is zero or negative, and unavailable_offsetting_rows when the total is positive but smaller in magnitude than at least one bucket (large offsetting buckets leaving a residue). In both cases rows and total are still returned exactly and percentages are not: a share of a non-positive base, or of a rounding residue, is not meaningful.
      - `total` ExactMoney, required: Exact money value: signed integer minor units as a string (never a float), with explicit currency and minor-unit exponent.
        - `amountMinor` string, required: Signed integer minor units, e.g. "80000" = $800.00 at exponent 2.
        - `currency` string, required
        - `minorUnitExponent` integer, required
      - `rows` object[], required
        - `key` string, required
        - `label` string, required
        - `money` ExactMoney, required: Exact money value: signed integer minor units as a string (never a float), with explicit currency and minor-unit exponent.
          - `amountMinor` string, required: Signed integer minor units, e.g. "80000" = $800.00 at exponent 2.
          - `currency` string, required
          - `minorUnitExponent` integer, required
        - `percentBasisPoints` integer: Present only when percentageStatus is available, which also bounds it to [-10000, 10000]: no bucket's magnitude exceeds the total, so the value is always exactly representable. Negative for a bucket whose signed net is negative (refunds exceeding spend).

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `422`: Request failed validation
- `503`: The legal-entity scope authority could not be read

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)