tools

Search transactions

Use this when the user asks to find transactions or total a filtered set of transactions. Search transactions by date, merchant, category, trait, type/class, account, or amount; a summary totals all matches. Brokerage deposits/withdrawals: transactionClass brokerage, transactionTypes transfer_in/transfer_out/deposit/withdrawal.

post/v1/tools/betteroff_search_transactions

Request

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

Request body

allTimeboolean nullable

Use true for all synced merchant history; dates are ignored. Use it when the answer may be older than the default 30 days: the last or first time, ever, annual or one-off charges, or 'did I pay X before'.

startDatestring date nullable required

Start date (ISO format, e.g. 2025-01-01). Use null for 30 days ago.

endDatestring date nullable required

End date (ISO format). Use null for today.

merchantstring nullable required

Merchant name to search for (partial match).

traitsstring[] nullable required

Only transactions whose merchant has every listed trait. Use for purposes a category does not capture. discretionary: optional spending: dining out, entertainment, hobbies, shopping for wants; travel: trips: flights, hotels, rental cars, cruises, travel booking; health: medical care: doctors, dentists, pharmacies, vision, therapy; kids: children: childcare, schools, tutoring, toys, kids' activities; gifts: gifts: florists, gift shops, gift cards; charity: donations: charities, nonprofits, religious organizations, fundraisers; business: work expenses: software, office supplies, coworking, professional services; crypto: crypto: exchanges, on-ramps, wallets, crypto cards. Person-to-person payments and unrecognized merchants carry no traits. Use null for no trait filter.

categorystring nullable required

Category code (e.g. FOOD_AND_DRINK, TRANSPORTATION, ENTERTAINMENT).

transactionTypesstring[] nullable required

Filter by transaction type. For investment account deposits/withdrawals, use transfer_in/deposit/bank_deposit for deposits and transfer_out/withdrawal/bank_withdrawal for withdrawals.

transactionClass'bank' | 'brokerage' | 'crypto_exchange' | 'blockchain_wallet' nullable required

Filter by normalized transaction class. Use brokerage for investment accounts.

accountIdstring nullable required

Filter to a specific account by ID. Use null to search all accounts.

minAmountnumber nullable required

Minimum transaction amount.

maxAmountnumber nullable required

Maximum transaction amount.

limitinteger nullable required

Max results to return (default 25, max 50). Use null for 25.

Response

Tool result

OR

Changes

No recorded changes to this operation across all 1 revision of this API.