listTransactions

Reference

Authentication: bearer token required (see how to get a token)

List Transactions - retrieves transactions for the authenticated user with optional filtering.

This handler returns transactions from accounts where the user is either the owner or collaborator.
It supports comprehensive filtering by account, tags, vendors, categories, dates, amounts, and search queries.

Authentication: Required (Bearer token)

Parameters:
- pagination (object, optional): Controls result paging
  - limit (int): Max records to return, 0-100 (default 50; 0 also means the default)
  - skip (int): Number of records to skip (non-negative)
- sort (array, optional): Sort criteria (default: transactedAt DESC); only the first entry is applied
  - field (string): One of transactedAt, amount, name, vendorName, category, createdAt, updatedAt, _id
  - operator (string): Sort direction ("ASC" or "DESC")
- ids (array, optional): Filter by transaction IDs (at most 500, unique, non-empty)
- accountId (string, optional): Filter by single account ID (legacy, use accountIds)
- accountIds (array, optional): Filter by multiple account IDs (at most 100, unique, non-empty)
- tagIds (array, optional): Filter transactions that have all specified tags (at most 500)
- vendorIds (array, optional): Filter by vendor IDs (at most 500)
- vendorNames (array, optional): Filter by vendor names (vendorId must be null/empty; at most 500)
- categories (array, optional): Filter by transaction categories (FOOD, RENT, INCOME, etc.; at most 500)
- categoryIds (array, optional): Filter by transaction category IDs (new category system; at most 500)
- sources (array, optional): Filter by transaction sources (BANK_INTEGRATION, MANUAL, etc.; at most 500)
- startDate (string, optional): Filter transactions on or after this date (ISO 8601)
- endDate (string, optional): Filter transactions on or before this date (ISO 8601)
- searchQuery (string, optional): Case-insensitive literal substring match on transaction name, description, or vendor name
- transactionType (string, optional): Filter by type ("INCOME", "EXPENSE", "TRANSFER")
- minAmountInclusive (number, optional): Minimum transaction amount (inclusive)
- maxAmountInclusive (number, optional): Maximum transaction amount (inclusive)
- minimumAbsoluteAmountInclusive (number, optional): Minimum absolute amount (inclusive, matches positive or negative)
- maximumAbsoluteAmountInclusive (number, optional): Maximum absolute amount (inclusive, matches positive or negative)
- includeUntagged (boolean, optional): Include untagged transactions when filtering by tags

Returns:
- transactions (array): Array of transaction objects
- numItems (int): Total number of transactions matching the filter (ignoring limit)

Example:
{
  "method": "listTransactions",
  "params": {
    "pagination": {
      "limit": 20,
      "skip": 0
    },
    "sort": [
      {
        "field": "transactedAt",
        "operator": "DESC"
      }
    ],
    "accountIds": ["account_123"],
    "categories": ["FOOD", "ENTERTAINMENT"],
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-12-31T23:59:59Z",
    "minAmountInclusive": -10000,
    "maxAmountInclusive": 0
  }
}