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

# Get Balance History

> Get historical balance time series (v2, ClickHouse-backed).

Reconstructs asset and liability balances over time using local ClickHouse data,
eliminating the round-trip to the Truv Core API. Returns the same response shape as v1.



## OpenAPI

````yaml GET /v2/users/balance-history
openapi: 3.1.0
info:
  title: Truv Public API
  description: >
    Read-only API for personal access token (PAT) users.


    ## Authentication


    Authenticate with `Authorization: Bearer <token>`. Tokens have a `pat_`
    prefix

    and are generated in the Truv web app under Settings → API keys.


    ## Available Endpoints


    This API exposes a subset of read-only endpoints for retrieving financial
    data,

    account links, and user profile information.
  version: 1.0.0
servers:
  - url: https://api.mytruv.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: users
    description: User profile — read-only access to the authenticated user's profile.
  - name: financial-data
    description: >-
      Financial data — balances, transactions, income, spending, liabilities,
      and balance history.
  - name: links
    description: >-
      Account links — list connected financial institutions and payroll
      providers.
paths:
  /v2/users/balance-history:
    get:
      tags:
        - financial-data
      summary: Get User Balance History V2
      description: >-
        Get historical balance time series (v2, ClickHouse-backed).


        Reconstructs asset and liability balances over time using local
        ClickHouse data,

        eliminating the round-trip to the Truv Core API. Returns the same
        response shape as v1.
      operationId: getBalanceHistoryV2
      parameters:
        - name: link_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter by specific link IDs. Omit to include all links.
            title: Link Ids
          description: Filter by specific link IDs. Omit to include all links.
        - name: account_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter by specific account IDs. Omit to include all accounts.
            title: Account Ids
          description: Filter by specific account IDs. Omit to include all accounts.
        - name: date_range
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/BalanceHistoryDateRange'
            description: >-
              How far back to look. One of: 1_month, 3_months, 6_months, 1_year,
              all.
            default: 3M
          description: >-
            How far back to look. One of: 1_month, 3_months, 6_months, 1_year,
            all.
        - name: time_period
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/BalanceHistoryTimePeriod'
            description: 'Aggregation granularity for data points. One of: day, week, month.'
            default: week
          description: 'Aggregation granularity for data points. One of: day, week, month.'
      responses:
        '200':
          description: Historical balance time series (v2, ClickHouse-backed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BalanceHistoryDateRange:
      type: string
      enum:
        - 1M
        - 3M
        - 6M
        - 1Y
        - ALL
      title: BalanceHistoryDateRange
      description: Supported date ranges for balance history queries.
    BalanceHistoryTimePeriod:
      type: string
      enum:
        - day
        - week
        - month
      title: BalanceHistoryTimePeriod
      description: Aggregation granularity for balance history data points.
    BalanceHistoryResponse:
      properties:
        time_series:
          items:
            $ref: '#/components/schemas/BalanceHistoryPoint'
          type: array
          title: Time Series
          description: Chronologically ordered data points.
        date_range:
          type: string
          title: Date Range
          description: Date range code used for this query.
          examples:
            - 3M
        start_date:
          type: string
          title: Start Date
          description: Start date of the time series (YYYY-MM-DD).
          examples:
            - '2025-11-01'
        end_date:
          type: string
          title: End Date
          description: End date of the time series (YYYY-MM-DD).
          examples:
            - '2026-02-01'
      type: object
      required:
        - time_series
        - date_range
        - start_date
        - end_date
      title: BalanceHistoryResponse
      description: >-
        Balance history time series showing assets, liabilities, and net worth
        over time.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BalanceHistoryPoint:
      properties:
        date:
          type: string
          title: Date
          description: Date of this data point (YYYY-MM-DD).
          examples:
            - '2025-11-03'
        assets:
          type: string
          title: Assets
          description: Total asset balance as a decimal string.
          examples:
            - '98635.00'
        liabilities:
          type: string
          title: Liabilities
          description: Total liability balance as a decimal string.
          examples:
            - '58320.75'
        net_worth:
          type: string
          title: Net Worth
          description: Net worth (assets minus liabilities) as a decimal string.
          examples:
            - '40314.25'
      type: object
      required:
        - date
        - assets
        - liabilities
        - net_worth
      title: BalanceHistoryPoint
      description: A single data point in the balance history time series.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: PAT
      description: >-
        Bearer authentication with a personal access token (prefix `pat_`).
        Generate tokens in the Truv web app under Settings → API keys.

````