---
title: "Posted-books cash balance series (daily, or completed-month with granularity=month)"
method: GET
path: "/companies/{companyId}/metrics/cash-history"
tags: ["Overview"]
---

# Posted-books cash balance series (daily, or completed-month with granularity=month)

`GET /companies/{companyId}/metrics/cash-history`

## Request

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

Returns the daily posted-books cash balance series behind the Home hero cash card's trend chart. Cash accounts resolve through the same rule the overview uses; the opening balance is the cumulative POSTED journal-line balance before the window start, and the series then walks the window's posted journal lines day by day — one point per day with activity, plus window-boundary points. Entity-scoped when `entityId` is given. `available` is false with `series: []` when the company has no cash accounts or no posted cash journal lines at all.

## Query parameters

- `entityId` string, uuid
- `months` integer
- `granularity` 'day' | 'month'

## Response `200`

Cash-history payload

- union
  - CashHistoryResponse
    - `success` true, required
    - `data` CashHistoryData, required
      - `available` boolean, required: False when the company has no cash accounts or no posted cash journal lines at all (series empty).
      - `basis` 'posted-books', required
      - `series` CashHistoryPoint[], required: Ascending by date; one point per day with activity plus window-boundary points (a flat window is just the boundary points).
        - `date` string, date, required
        - `balanceCents` integer, required: Cumulative posted cash balance at the end of this date, in cents.
  - MonthlyCashHistoryResponse
    - `success` true, required
    - `data` MonthlyCashHistoryData, required
      - `granularity` 'month', required
      - `currentCash` object, required: MetricResult of ExactMoney. available:false carries `reason` (insufficient_history | entity_scope_unavailable | incomplete_provenance | mixed_currency | truncated | failed) and never a value.
        - `available` boolean, required
        - `reason` string
        - `value` ExactMoney: 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
        - `authority` MonthlyCashHistoryMetricAuthority
          - `companyId` string, uuid, required
          - `entityId` string, uuid, required
          - `basis` 'posted_books_cash', required
          - `asOf` string, required: Live ISO instant for `currentCash`; the window's last completed month (YYYY-MM) for `history` — deliberately different clocks.
          - `startMonth` string
          - `endMonth` string
          - `monthKeys` string[]
        - `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
      - `history` object, required: MetricResult of a completed-month MoneySeries. Numeric slots are {month, state: observed|authoritative_zero, money: ExactMoney}; pre-history padding is omitted (authority.monthKeys names the full requested window); a wholly unavailable series returns nonnumeric slots in `diagnostic`.
        - `available` boolean, required
        - `reason` string
        - `value` object
          - `slots` object[], required
            - `month` string, required
            - `state` 'observed' | 'authoritative_zero', required
            - `money` ExactMoney, required: Exact money value: signed integer minor units as a string (never a float), with explicit currency and minor-unit exponent.
              - …
        - `diagnostic` object
          - `slots` object[]
            - `month` string, required
            - `state` 'unavailable' | 'padding', required
        - `authority` MonthlyCashHistoryMetricAuthority
          - `companyId` string, uuid, required
          - `entityId` string, uuid, required
          - `basis` 'posted_books_cash', required
          - `asOf` string, required: Live ISO instant for `currentCash`; the window's last completed month (YYYY-MM) for `history` — deliberately different clocks.
          - `startMonth` string
          - `endMonth` string
          - `monthKeys` string[]
        - `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

## 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)