Find transactions

Search for transactions by description, date, amount or account with transaction.find; list an account's register with transaction.list; find business documents with invoice.list.

There are two ways to look at transactions. transaction.list is a register: all transactions, or those of one account and a date range, in GnuCash's order. transaction.find is GnuCash's Find Transaction dialog: it matches splits against criteria you combine.

Steps

To read an account, call transaction.list with account and, if you like, from and to. With no parameters it lists the whole book, which is GnuCash's General Journal.
To search, call transaction.find with a query. A query is a criterion or a group of criteria: {"all": [...]} means every one must match, {"any": [...]} means at least one, {"not": ...} negates. Criteria include description, notes, memo, num, datePosted, value, amount, reconcile, void and accounts; the reference page lists them with their operators. Add limit to keep only the last matches.
Read the matches. Each is a split (split) with its transaction and account. Several matches may belong to one transaction; pass its GUID to transaction.get for the whole thing.
Business documents are found with invoice.list, filtered by type (invoice, bill, expenseVoucher, creditNote), posted and owner. See Invoices and bills.

Example

Example: with a copy of the reports/test-data example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"transaction.list","params":{"account":"Root:Asset:Wallet","from":"1971-01-01","to":"1971-12-31"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transactions": [
      {
        "guid": "c0000000000000000000000000000007",
        "description": "$100bank -> $80expenses + $20wallet",
        "…": "…"
      }
    ]
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"transaction.find","params":{"query":{"all":[{"description":{"text":"$22 expense"}},{"datePosted":{"op":"before","date":"1978-03-01"}}]}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "matches": [
      {
        "transaction": "c000000000000000000000000000000d",
        "split": "…",
        "account": "…"
      },
      "…"
    ]
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"invoice.list","params":{"posted":false}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "invoices": []
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
transaction.list {"account":"Root:Asset:Wallet","from":"1971-01-01","to":"1971-12-31"}
transaction.find {"query":{"all":[{"description":{"text":"$22 expense"}},{"datePosted":{"op":"before","date":"1978-03-01"}}]}}
invoice.list {"posted":false}
EOF

It prints:

[
  {
    "transactions": [
      {
        "guid": "c0000000000000000000000000000007",
        "description": "$100bank -> $80expenses + $20wallet",
        "…": "…"
      }
    ]
  },
  {
    "matches": [
      {
        "transaction": "c000000000000000000000000000000d",
        "split": "…",
        "account": "…"
      },
      "…"
    ]
  },
  {
    "invoices": []
  }
]

MCP tool call

Tool call:

{"name":"transaction.list","arguments":{"account":"Root:Asset:Wallet","from":"1971-01-01","to":"1971-12-31"}}

Result:

{
  "structuredContent": {
    "transactions": [
      {
        "guid": "c0000000000000000000000000000007",
        "description": "$100bank -> $80expenses + $20wallet",
        "…": "…"
      }
    ]
  }
}

Tool call:

{"name":"transaction.find","arguments":{"query":{"all":[{"description":{"text":"$22 expense"}},{"datePosted":{"op":"before","date":"1978-03-01"}}]}}}

Result:

{
  "structuredContent": {
    "matches": [
      {
        "transaction": "c000000000000000000000000000000d",
        "split": "…",
        "account": "…"
      },
      "…"
    ]
  }
}

Tool call:

{"name":"invoice.list","arguments":{"posted":false}}

Result:

{
  "structuredContent": {
    "invoices": []
  }
}