list_transactions
Retrieve budget transactions from YNAB with filters for date, type, category, payee, or account to analyze spending patterns.
Instructions
Get transactions for a budget. Supports filtering by date, type, category, payee, and account.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | Yes | The budget ID | |
| since_date | No | Only return transactions on or after this date (YYYY-MM-DD) | |
| type | No | Filter by transaction type | |
| category_id | No | Filter by category ID | |
| payee_id | No | Filter by payee ID | |
| account_id | No | Filter by account ID |
Implementation Reference
- src/index.ts:61-92 (handler)Core handler function in YNABClient class that implements the list_transactions tool logic by querying the YNAB API and applying client-side filters.async listTransactions(budgetId: string, params?: { sinceDate?: string; type?: string; categoryId?: string; payeeId?: string; accountId?: string; }) { let path = `/budgets/${budgetId}/transactions`; const queryParams: string[] = []; if (params?.sinceDate) queryParams.push(`since_date=${params.sinceDate}`); if (params?.type) queryParams.push(`type=${params.type}`); if (queryParams.length > 0) { path += `?${queryParams.join("&")}`; } let result = await this.request<{ transactions: any[] }>(path); // Client-side filtering for category and payee if (params?.categoryId) { result.transactions = result.transactions.filter(t => t.category_id === params.categoryId); } if (params?.payeeId) { result.transactions = result.transactions.filter(t => t.payee_id === params.payeeId); } if (params?.accountId) { result.transactions = result.transactions.filter(t => t.account_id === params.accountId); } return result; }
- src/index.ts:130-137 (schema)Zod schema used for input validation in the list_transactions tool handler.const TransactionsSchema = z.object({ budget_id: z.string().describe("The budget ID"), since_date: z.string().optional().describe("Only return transactions on or after this date (ISO format: YYYY-MM-DD)"), type: z.enum(["uncategorized", "unapproved"]).optional().describe("Filter by transaction type"), category_id: z.string().optional().describe("Filter by category ID"), payee_id: z.string().optional().describe("Filter by payee ID"), account_id: z.string().optional().describe("Filter by account ID"), });
- src/index.ts:217-232 (registration)Tool registration entry in the tools array, defining name, description, and input schema for list_tools request.{ name: "list_transactions", description: "Get transactions for a budget. Supports filtering by date, type, category, payee, and account.", inputSchema: { type: "object" as const, properties: { budget_id: { type: "string", description: "The budget ID" }, since_date: { type: "string", description: "Only return transactions on or after this date (YYYY-MM-DD)" }, type: { type: "string", enum: ["uncategorized", "unapproved"], description: "Filter by transaction type" }, category_id: { type: "string", description: "Filter by category ID" }, payee_id: { type: "string", description: "Filter by payee ID" }, account_id: { type: "string", description: "Filter by account ID" }, }, required: ["budget_id"], }, },
- src/index.ts:349-359 (handler)Dispatch handler in the main CallToolRequestSchema handler that parses input and invokes the listTransactions method.case "list_transactions": { const params = TransactionsSchema.parse(args); result = await client.listTransactions(params.budget_id, { sinceDate: params.since_date, type: params.type, categoryId: params.category_id, payeeId: params.payee_id, accountId: params.account_id, }); break; }