get_transactions
Retrieve and filter Copilot Money transactions by date, category, merchant, amount, tag, or location, or look one up by ID. Search merchant text and pull special types like refunds, credits, and duplicates.
Instructions
Reads from the local LevelDB cache, which may lag behind Copilot's server if the macOS app hasn't synced recently. For real-time data use --live-reads with get_transactions_live. Unified transaction retrieval tool. Supports multiple modes: (1) Filter-based: Use period, date range, category, merchant, amount filters. (2) Single lookup: Provide transaction_id to get one transaction. (3) Text search: Use query for free-text merchant search. (4) Special types: Use transaction_type for foreign, refunds, credits, duplicates, hsa_eligible, tagged. (5) Location-based: Use city or lat/lon with radius_km. (6) Tag filter: Use tag to find transactions with a specific tag. Rows are TERSE by default: transaction_id, date, amount, name, category_name, account_id, item_id, pending, excluded, internal_transfer. excluded answers "is this row excluded from spending?" — the raw per-transaction flag OR the row's category being user-excluded, the same union exclude_excluded filters on — so it is true for a row Copilot never stamped individually. It is therefore nearly always false in a default response, since exclude_excluded already removed those rows; it carries information only when you pass exclude_excluded: false. A cache row carries ~30 fields and most callers need a handful, so the rest are excluded unless asked for. PARTIAL list of what that drops, not exhaustive: Plaid metadata (plaid_category_id, plaid_category_strings, plaid_deleted), internal IDs (category_id, recurring_id, goal_id, parent_transaction_id, children_transaction_ids, user_id), enrichment and intelligence fields (normalized_merchant — still the normalized merchant name when requested — intelligence_suggested_category_ids, suggestion_ids, original_name), tag_ids, review state (user_reviewed, user_note, user_changed_type — true only when a human re-typed the row, so do not second-guess its type), location (city, region, country, lat/lon), and flags like is_amazon/from_investment. amazon is worth naming because nothing else hints it exists: on rows Copilot matched to an Amazon order it carries the receipt — {order_id, items: [{id, name, link, price, quantity}], other: {giftWrapping, rewards, savings, shipping, tax}} — so fields: ["default", "amazon"] answers "what was in this order" without an exported CSV. Ask for any of them by name with fields: ["default", "tag_ids"], or take the whole document with fields: ["all"] (or "*"). category_name is always resolved to a human-readable name. compact was removed in v3.0.0 — passing it now raises an error naming this migration.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude for proximity search (use with lon and radius_km) | |
| lon | No | Longitude for proximity search (use with lat and radius_km) | |
| tag | No | Filter by tag name (e.g. "vacation") | |
| city | No | Filter by city name (partial match) | |
| limit | No | Maximum number of results (default: 100) | |
| query | No | Free-text search in merchant/transaction names | |
| fields | No | Return only these fields per transaction. Default when omitted: a terse row (transaction_id, date, amount, name, category_name, account_id, item_id, pending, excluded, internal_transfer). Anything else is requestable by name alongside the preset: fields: ["default", "tag_ids"], or "all" / "*" for the whole row. THIS TOOL's own description names what its rows drop — the two modes drop different things, because a live row is not a cache document. The note is user_note in cache mode and user_notes live; either spelling works in either mode, and each mode returns its own. Unknown names are omitted and reported via _field_warning. | |
| offset | No | Number of results to skip for pagination (default: 0) | |
| period | No | Period shorthand: this_month, last_month, last_7_days, last_30_days, last_90_days, ytd, this_year, last_year | |
| region | No | Filter by region/city (case-insensitive substring) | |
| country | No | Filter by country code (e.g., US, CL) | |
| pending | No | Filter by pending status (true for pending only, false for settled only) | |
| category | No | Filter by category ID from get_categories (exact match, not a name). A parent category's id also returns its subcategories' rows. An id that belongs to no category and to no transaction the call looked at is an error. | |
| end_date | No | End date (YYYY-MM-DD) | |
| merchant | No | Filter by merchant name (case-insensitive substring) | |
| radius_km | No | Search radius in kilometers (default: 10) | |
| account_id | No | Filter by account ID | |
| max_amount | No | Maximum transaction amount | |
| min_amount | No | Minimum transaction amount | |
| start_date | No | Start date (YYYY-MM-DD) | |
| transaction_id | No | Get a single transaction by ID (ignores other filters, though a `category` value must still be a real id) | |
| exclude_deleted | No | Exclude deleted transactions marked by Plaid (default: true) | |
| exclude_excluded | No | Exclude user-excluded transactions (default: true) | |
| transaction_type | No | Filter by special type. Cache-only: foreign (international) and duplicates (potential duplicate transactions, paired among the rows the other filters keep; pass the matching exclude_*: false, e.g. exclude_deleted: false, to bring a hidden copy back). Same rule in cache and live mode (positive amount = money out). refunds: a negative REGULAR row in a spending category; never INCOME, a transfer or uncategorized. credits: a negative REGULAR row whose name has credit/cashback/reward/rebate/bonus and whose category is not income or transfer; may overlap refunds. hsa_eligible: a heuristic, not an eligibility ruling: a positive REGULAR row whose category name has health/medical/pharmac/dental/eye care/vision or whose name has cvs/walgreens/pharmacy/medical/dental/vision/hospital. tagged: has a tag. type_specific_data totals cover all matching rows, not just the returned page. | |
| exclude_transfers | No | Exclude transfers between accounts and credit card payments (default: true) | |
| exclude_split_parents | No | Exclude split-transaction parents (docs with children_transaction_ids). The children already carry the real categorized amounts — returning the parent would double-count the spend. Default: true. |