---
title: "Get account flows"
method: POST
path: "/v1/tools/betteroff_get_account_flows"
tags: ["tools"]
---

# Get account flows

`POST /v1/tools/betteroff_get_account_flows`

## Request

- Base URL: `https://api.betteroff.finance`
- URL: `https://api.betteroff.finance/v1/tools/betteroff_get_account_flows`
- Auth: one of:
  - OpenID Connect (`https://app.betteroff.finance/api/auth/.well-known/openid-configuration`, scopes: `accounts:read`, `transactions:read`)
  - HTTP bearer

Use this when the user asks how much entered or left specific accounts. Gross inflows, gross outflows, and net flow for selected accounts over a date range, aggregated over ALL matches server-side, e.g. 'how much did I deposit into Schwab this year'. Prefer this over betteroff_search_transactions for deposit/withdrawal totals.

## Request body

- object
  - `startDate` string, date, nullable, required: Start date (ISO format, e.g. 2026-01-01). Use null for Jan 1 of this year.
  - `endDate` string, date, nullable, required: End date (ISO format). Use null for today.
  - `accountIds` string[], nullable, required: Specific account IDs to include. Use null to select by accountType/institution.
  - `accountType` 'depository' | 'investment' | 'credit' | 'loan' | 'crypto' | 'wallet', nullable, required: Optional account type filter. Use investment for brokerage/retirement accounts.
  - `institution` string, nullable, required: Optional institution name filter, e.g. Charles Schwab. Partial matches are accepted.
  - `direction` 'all' | 'inflow' | 'outflow', nullable, required: Use inflow for deposits only, outflow for withdrawals only, all for both.
  - `limit` integer, nullable, required: Max transaction rows to return for evidence (default 25, max 100).

## Response `200`

Tool result

- union
  - object
    - `ok` false, required
    - `requestId` string
    - `error` string, required
    - `code` string, required
    - `retryable` boolean, required
    - `nextStep` string, required
    - `field` string
    - `missingInputs` object[]
      - `id` string, required
      - `name` string, required
      - `balanceMissing` boolean, required
      - `interestRateMissing` boolean, required
      - `minimumPaymentMissing` boolean, required
  - object
    - `ok` true, required
    - `requestId` string
    - `schemaVersion` '4', required
    - `data` object, required
      - `period` object, required
        - `start` string, nullable, required
        - `end` string, nullable, required
      - `filters` object, required
      - `summary` object, required
        - `currency` string, required
        - `deposited` string, required: Decimal text, e.g. "-12.50". Read the currency beside it or on the result.
        - `withdrawn` string, required: Decimal text, e.g. "-12.50". Read the currency beside it or on the result.
        - `net` string, required: Decimal text, e.g. "-12.50". Read the currency beside it or on the result.
        - `depositCount` integer, required
        - `withdrawalCount` integer, required
        - `matchingCount` integer, required
      - `accounts` object[], required
        - `id` string, uuid, required
        - `name` string, nullable, required
        - `officialName` string, nullable, required
        - `type` string, required
        - `subtype` string, nullable, required
        - `mask` string, nullable, required
        - `institution` string, nullable, required
        - `currency` string, required
        - `deposited` string, required: Decimal text, e.g. "-12.50". Read the currency beside it or on the result.
        - `withdrawn` string, required: Decimal text, e.g. "-12.50". Read the currency beside it or on the result.
        - `net` string, required: Deposited minus withdrawn, in currency. Negative is a net outflow.
        - `depositCount` integer, required
        - `withdrawalCount` integer, required
        - `connectionHealth` object, nullable, required
      - `transactions` object[], required
        - `id` string, uuid, required
        - `name` string, nullable, required
        - `amount` string, required: Decimal text in the row's currency. Positive is an outflow; negative is an inflow.
        - `absoluteAmount` string, required: Decimal text, e.g. "-12.50". Read the currency beside it or on the result.
        - `currency` string, required
        - `date` string, required
        - `direction` 'inflow' | 'outflow', required
        - `flowLabel` 'deposit' | 'withdrawal', required
        - `transactionType` string, required
        - `transactionClass` string, nullable, required
        - `category` string, nullable, required
        - `subcategory` string, nullable, required
        - `status` string, required
        - `account` string, required
    - `currency` string, nullable, required
    - `timezone` string, required
    - `asOf` string, nullable, required
    - `revision` integer, required
    - `householdRevision` integer, required
    - `quality` object, required
      - `state` 'complete' | 'partial' | 'unavailable', required
      - `reasons` string[], required
    - `evidence` object[], required
      - `source` string, required
      - `id` string
      - `observedAt` string, nullable, required
    - `page` object, required
      - `returnedCount` integer, required
      - `totalCount` integer, nullable, required
      - `truncated` boolean, required
      - `nextCursor` Schema2, required (unresolved $ref)
    - `warnings` string[], required
    - `notes` string

## Other responses

- `400`: INVALID_INPUT (a missing, unknown, or invalid argument, named in `fields`), TOOL_CALL_REJECTED, or a body that is not JSON.
- `401`: AGENT_TOKEN_INVALID: the token is missing, expired, or revoked.
- `402`: AGENT_SUBSCRIPTION_INACTIVE or FEATURE_NOT_INCLUDED: needs BetterOff Core.
- `403`: INSUFFICIENT_SCOPE, ACCESS_DENIED, or AGENT_GRANT_REVOKED.
- `404`: TOOL_NOT_FOUND, or NOT_FOUND for a record the org does not have.
- `409`: CONFLICT: the record's state rules this call out. Read it again.
- `422`: INCOMPLETE_DATA or RESULT_TOO_LARGE. Narrow the request; don't retry as is.
- `429`: RATE_LIMITED. Retry after Retry-After seconds.
- `503`: DATA_UNAVAILABLE, DEPENDENCY_UNAVAILABLE (including the 25-second tool deadline), or AGENT_AUTHZ_UNAVAILABLE. Retryable.
- `default`: Problem details

---

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