> ## Documentation Index > Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt > Use this file to discover all available pages before exploring further. # Aggregate Balance Ledger > Returns a customer's balance of a feature at each UTC hour or day of a range, and at each change other than a track, for charting it over time. Returns a customer's balance of a feature over time, for a chart: one `bin` point at each UTC hour or day of the range, and one `change` point at each entry other than a track, such as a plan change or a reset. A change point's `entry_id` is its entry in [List Balance Ledger](https://docs.useautumn.com/api-reference/balances/listBalanceLedger.md). The range defaults to the last seven days. It can cover up to 400 days, and up to 14 days with `bin_size: "hour"`. `bin_size` defaults to `hour` for ranges up to seven days and `day` above. > [!NOTE] > > Balance history is rolling out and isn't available for every customer yet; `coverage` says whether it is for this one. > [!NOTE] > > A point's `exact` is false where it is an estimate, for example before `coverage.since`, where some history is missing, or across an adjustment Autumn couldn't place. `adjustment` on a change point marks such an adjustment; the matching `adjustment` entry in [List Balance Ledger](https://docs.useautumn.com/api-reference/balances/listBalanceLedger.md) says what made it. An adjustment Autumn placed has a change point of its own and leaves the points around it exact; that change point alone is an estimate when usage in the same bin came both before and after it. > [!NOTE] > > Known limit: rarely, when a customer's id is changed, two changes to their balance recorded in the same millisecond can be placed in the wrong order here, so a point beside them can show `exact: true` while it is off. [List Balance Ledger](https://docs.useautumn.com/api-reference/balances/listBalanceLedger.md) orders them correctly. ### Body Parameters The customer whose balance to chart. The feature whose balance to chart. Chart this entity's own balance of the feature. For an entity with no balance of its own, the customer's balance is charted. The range to chart: at most 400 days, and at most 14 days with bin\_size hour. **properties** Start of the chart (epoch milliseconds), rounded down to the bin. Defaults to seven days before end. End of the chart (epoch milliseconds), rounded up to the bin and never past now. Defaults to now. A point per UTC hour or per UTC day. Defaults to hour for ranges up to seven days and day above. ### Response The first point's time (epoch milliseconds). The last point's time (epoch milliseconds). The entity whose own balance is charted, or null for the customer's. How much of this customer's balance history Autumn holds. Balance history is rolling out and isn't available for every customer yet; coverage says whether it is for this one. **properties** Whether Autumn is recording every change to this customer's balance now. While false, some or all changes may be missing (tracks may still be recorded), so a history that is empty or missing changes is expected. The earliest time history covers for this customer (epoch milliseconds), or null when nothing has been recorded yet. There are no entries from before it. The balance now, where the chart starts walking back from; null for an unlimited balance or none, with no points. **properties** The balance; null where there was none. **properties** Everything granted on the balance, rollovers included. What was left to use. What had been used. The balances behind the totals. Rollovers are not listed; where every balance is exact, the totals minus these balances is what rollovers hold. **properties** The balance, the same id as balance\_id in a track's deductions. In a customer's view of a balance that each entity holds its own share of, the entity this share belongs to; null otherwise. False where history cannot pin this balance down, for example across an adjustment Autumn couldn't place. Where every balance is exact, the totals minus the balances is what rollovers hold. Oldest first. **properties** The balance; null where there was none. **properties** Everything granted on the balance, rollovers included. What was left to use. What had been used. The balances behind the totals. Rollovers are not listed; where every balance is exact, the totals minus these balances is what rollovers hold. **properties** The balance, the same id as balance\_id in a track's deductions. In a customer's view of a balance that each entity holds its own share of, the entity this share belongs to; null otherwise. False where history cannot pin this balance down, for example across an adjustment Autumn couldn't place. Where every balance is exact, the totals minus the balances is what rollovers hold. Epoch milliseconds. The point counts everything Autumn recorded before this time, and a change point's own entry. bin: the boundary of an hour or day, start and end included. change: an entry other than a track, such as a plan change, a reset or an adjustment Autumn placed, at the time Autumn recorded it. On a change point, the id of its balances.list\_ledger entry; null on a bin point. On a change point, the balance just before the change; null on a bin point. **properties** The balance; null where there was none. **properties** Everything granted on the balance, rollovers included. What was left to use. What had been used. The balances behind the totals. Rollovers are not listed; where every balance is exact, the totals minus these balances is what rollovers hold. **properties** The balance, the same id as balance\_id in a track's deductions. In a customer's view of a balance that each entity holds its own share of, the entity this share belongs to; null otherwise. False where history cannot pin this balance down, for example across an adjustment Autumn couldn't place. Where every balance is exact, the totals minus the balances is what rollovers hold. False where the point is an estimate: before coverage.since, across missing history, across an adjustment Autumn couldn't place, or where a balance several entities share ran into overage or was refunded. On a change point, set when what its entry says it left differs from what came after and Autumn couldn't place the adjustment: it happened between this change and the next newer one. The matching adjustment entry in balances.list\_ledger says what made it. **properties** The balances the adjustment moved; empty when only the totals differ. ```json 200 theme={null} { "start": 1761602400000, "end": 1761613200000, "bin_size": "hour", "entity_id": null, "coverage": { "recording": true, "since": 1759300000000 }, "current": { "totals": { "granted": 1000, "remaining": 960, "usage": 40 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "plan_id": "pro", "granted": 1000, "remaining": 960, "usage": 40, "exact": true } ] }, "points": [ { "totals": { "granted": 1000, "remaining": 180, "usage": 820 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "plan_id": "pro", "granted": 1000, "remaining": 180, "usage": 820, "exact": true } ], "at": 1761602400000, "kind": "bin", "entry_id": null, "before": null, "exact": true, "adjustment": null }, { "totals": { "granted": 1000, "remaining": 150, "usage": 850 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "plan_id": "pro", "granted": 1000, "remaining": 150, "usage": 850, "exact": true } ], "at": 1761606000000, "kind": "bin", "entry_id": null, "before": null, "exact": true, "adjustment": null }, { "totals": { "granted": 1000, "remaining": 120, "usage": 880 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "plan_id": "pro", "granted": 1000, "remaining": 120, "usage": 880, "exact": true } ], "at": 1761609600000, "kind": "bin", "entry_id": null, "before": null, "exact": true, "adjustment": null }, { "totals": { "granted": 1000, "remaining": 1000, "usage": 0 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "plan_id": "pro", "granted": 1000, "remaining": 1000, "usage": 0, "exact": true } ], "at": 1761609600412, "kind": "change", "entry_id": "hist_Y2hhbmdlXzM", "before": { "totals": { "granted": 1000, "remaining": 120, "usage": 880 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "plan_id": "pro", "granted": 1000, "remaining": 120, "usage": 880, "exact": true } ] }, "exact": true, "adjustment": null }, { "totals": { "granted": 1000, "remaining": 960, "usage": 40 }, "breakdown": [ { "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2", "entity_id": null, "plan_id": "pro", "granted": 1000, "remaining": 960, "usage": 40, "exact": true } ], "at": 1761613200000, "kind": "bin", "entry_id": null, "before": null, "exact": true, "adjustment": null } ] } ``` ## OpenAPI ````yaml openapi POST /v1/balances.aggregate_ledger openapi: 3.1.0 info: title: Autumn API version: 2.6.0 servers: - url: https://api.useautumn.com description: Production server security: - secretKey: [] paths: /v1/balances.aggregate_ledger: post: tags: - balances description: >- Returns a customer's balance of a feature at each UTC hour or day of a range, and at each change other than a track, for charting it over time. operationId: aggregateBalanceLedger parameters: - name: x-api-version in: header required: true schema: type: string default: 2.6.0 x-speakeasy-globals-hidden: true requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string minLength: 1 description: The customer whose balance to chart. feature_id: type: string minLength: 1 description: The feature whose balance to chart. entity_id: type: string minLength: 1 description: >- Chart this entity's own balance of the feature. For an entity with no balance of its own, the customer's balance is charted. custom_range: type: object properties: start: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Start of the chart (epoch milliseconds), rounded down to the bin. Defaults to seven days before end. end: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- End of the chart (epoch milliseconds), rounded up to the bin and never past now. Defaults to now. description: >- The range to chart: at most 400 days, and at most 14 days with bin_size hour. bin_size: enum: - hour - day type: string description: >- A point per UTC hour or per UTC day. Defaults to hour for ranges up to seven days and day above. required: - customer_id - feature_id title: AggregateBalanceLedgerParams examples: - customer_id: cus_123 feature_id: messages - customer_id: cus_123 feature_id: messages custom_range: start: 1759276800000 end: 1761868800000 bin_size: day example: customer_id: cus_123 feature_id: messages responses: '200': description: OK content: application/json: schema: type: object properties: start: type: number description: The first point's time (epoch milliseconds). end: type: number description: The last point's time (epoch milliseconds). bin_size: enum: - hour - day type: string entity_id: anyOf: - type: string - type: 'null' description: >- The entity whose own balance is charted, or null for the customer's. coverage: type: object properties: recording: type: boolean description: >- Whether Autumn is recording every change to this customer's balance now. While false, some or all changes may be missing (tracks may still be recorded), so a history that is empty or missing changes is expected. since: anyOf: - type: number - type: 'null' description: >- The earliest time history covers for this customer (epoch milliseconds), or null when nothing has been recorded yet. There are no entries from before it. required: - recording - since description: >- How much of this customer's balance history Autumn holds. Balance history is rolling out and isn't available for every customer yet; coverage says whether it is for this one. current: anyOf: - type: object properties: totals: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- Everything granted on the balance, rollovers included. remaining: anyOf: - type: number - type: 'null' description: What was left to use. usage: anyOf: - type: number - type: 'null' description: What had been used. required: - granted - remaining - usage - type: 'null' description: The balance; null where there was none. breakdown: type: array items: type: object properties: balance_id: type: string description: >- The balance, the same id as balance_id in a track's deductions. entity_id: anyOf: - type: string - type: 'null' description: >- In a customer's view of a balance that each entity holds its own share of, the entity this share belongs to; null otherwise. plan_id: anyOf: - type: string - type: 'null' granted: type: number remaining: type: number usage: type: number exact: type: boolean description: >- False where history cannot pin this balance down, for example across an adjustment Autumn couldn't place. Where every balance is exact, the totals minus the balances is what rollovers hold. required: - balance_id - entity_id - plan_id - granted - remaining - usage - exact description: >- The balances behind the totals. Rollovers are not listed; where every balance is exact, the totals minus these balances is what rollovers hold. required: - totals - breakdown - type: 'null' description: >- The balance now, where the chart starts walking back from; null for an unlimited balance or none, with no points. points: type: array items: type: object properties: totals: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- Everything granted on the balance, rollovers included. remaining: anyOf: - type: number - type: 'null' description: What was left to use. usage: anyOf: - type: number - type: 'null' description: What had been used. required: - granted - remaining - usage - type: 'null' description: The balance; null where there was none. breakdown: type: array items: type: object properties: balance_id: type: string description: >- The balance, the same id as balance_id in a track's deductions. entity_id: anyOf: - type: string - type: 'null' description: >- In a customer's view of a balance that each entity holds its own share of, the entity this share belongs to; null otherwise. plan_id: anyOf: - type: string - type: 'null' granted: type: number remaining: type: number usage: type: number exact: type: boolean description: >- False where history cannot pin this balance down, for example across an adjustment Autumn couldn't place. Where every balance is exact, the totals minus the balances is what rollovers hold. required: - balance_id - entity_id - plan_id - granted - remaining - usage - exact description: >- The balances behind the totals. Rollovers are not listed; where every balance is exact, the totals minus these balances is what rollovers hold. at: type: number description: >- Epoch milliseconds. The point counts everything Autumn recorded before this time, and a change point's own entry. kind: enum: - bin - change type: string description: >- bin: the boundary of an hour or day, start and end included. change: an entry other than a track, such as a plan change, a reset or an adjustment Autumn placed, at the time Autumn recorded it. entry_id: anyOf: - type: string - type: 'null' description: >- On a change point, the id of its balances.list_ledger entry; null on a bin point. before: anyOf: - type: object properties: totals: anyOf: - type: object properties: granted: anyOf: - type: number - type: 'null' description: >- Everything granted on the balance, rollovers included. remaining: anyOf: - type: number - type: 'null' description: What was left to use. usage: anyOf: - type: number - type: 'null' description: What had been used. required: - granted - remaining - usage - type: 'null' description: The balance; null where there was none. breakdown: type: array items: type: object properties: balance_id: type: string description: >- The balance, the same id as balance_id in a track's deductions. entity_id: anyOf: - type: string - type: 'null' description: >- In a customer's view of a balance that each entity holds its own share of, the entity this share belongs to; null otherwise. plan_id: anyOf: - type: string - type: 'null' granted: type: number remaining: type: number usage: type: number exact: type: boolean description: >- False where history cannot pin this balance down, for example across an adjustment Autumn couldn't place. Where every balance is exact, the totals minus the balances is what rollovers hold. required: - balance_id - entity_id - plan_id - granted - remaining - usage - exact description: >- The balances behind the totals. Rollovers are not listed; where every balance is exact, the totals minus these balances is what rollovers hold. required: - totals - breakdown - type: 'null' description: >- On a change point, the balance just before the change; null on a bin point. exact: type: boolean description: >- False where the point is an estimate: before coverage.since, across missing history, across an adjustment Autumn couldn't place, or where a balance several entities share ran into overage or was refunded. adjustment: anyOf: - type: object properties: balance_ids: type: array items: type: string description: >- The balances the adjustment moved; empty when only the totals differ. required: - balance_ids - type: 'null' description: >- On a change point, set when what its entry says it left differs from what came after and Autumn couldn't place the adjustment: it happened between this change and the next newer one. The matching adjustment entry in balances.list_ledger says what made it. required: - totals - breakdown - at - kind - entry_id - before - exact - adjustment description: Oldest first. required: - start - end - bin_size - entity_id - coverage - current - points examples: - start: 1761602400000 end: 1761613200000 bin_size: hour entity_id: null coverage: recording: true since: 1759300000000 current: totals: granted: 1000 remaining: 960 usage: 40 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 960 usage: 40 exact: true points: - totals: granted: 1000 remaining: 180 usage: 820 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 180 usage: 820 exact: true at: 1761602400000 kind: bin entry_id: null before: null exact: true adjustment: null - totals: granted: 1000 remaining: 150 usage: 850 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 150 usage: 850 exact: true at: 1761606000000 kind: bin entry_id: null before: null exact: true adjustment: null - totals: granted: 1000 remaining: 120 usage: 880 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 120 usage: 880 exact: true at: 1761609600000 kind: bin entry_id: null before: null exact: true adjustment: null - totals: granted: 1000 remaining: 1000 usage: 0 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 1000 usage: 0 exact: true at: 1761609600412 kind: change entry_id: hist_Y2hhbmdlXzM before: totals: granted: 1000 remaining: 120 usage: 880 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 120 usage: 880 exact: true exact: true adjustment: null - totals: granted: 1000 remaining: 960 usage: 40 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 960 usage: 40 exact: true at: 1761613200000 kind: bin entry_id: null before: null exact: true adjustment: null example: start: 1761602400000 end: 1761613200000 bin_size: hour entity_id: null coverage: recording: true since: 1759300000000 current: totals: granted: 1000 remaining: 960 usage: 40 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 960 usage: 40 exact: true points: - totals: granted: 1000 remaining: 180 usage: 820 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 180 usage: 820 exact: true at: 1761602400000 kind: bin entry_id: null before: null exact: true adjustment: null - totals: granted: 1000 remaining: 150 usage: 850 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 150 usage: 850 exact: true at: 1761606000000 kind: bin entry_id: null before: null exact: true adjustment: null - totals: granted: 1000 remaining: 120 usage: 880 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 120 usage: 880 exact: true at: 1761609600000 kind: bin entry_id: null before: null exact: true adjustment: null - totals: granted: 1000 remaining: 1000 usage: 0 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 1000 usage: 0 exact: true at: 1761609600412 kind: change entry_id: hist_Y2hhbmdlXzM before: totals: granted: 1000 remaining: 120 usage: 880 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 120 usage: 880 exact: true exact: true adjustment: null - totals: granted: 1000 remaining: 960 usage: 40 breakdown: - balance_id: cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2 entity_id: null plan_id: pro granted: 1000 remaining: 960 usage: 40 exact: true at: 1761613200000 kind: bin entry_id: null before: null exact: true adjustment: null x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.aggregateLedger({ customerId: "cus_123", featureId: "messages", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.aggregate_ledger( customer_id="cus_123", feature_id="messages", ) components: securitySchemes: secretKey: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.