get-transactions-summary

Get an aggregated summary of transactions, scoped to either income or expenses. Returns totals, counts, and averages, optionally grouped by category, month, or both. Filters mirror get-transactions: account, date, amount range, category ids.

Input

Field	Type	Required	Description
account_ids	array<string> | null		Restrict to transactions on these account.id values (from get-accounts). Default: null.
category_ids	array<string> | null		Restrict to these category ids (the id field from get-categories). Default: null.
direction	"Income" | "Expenses"	✓	Restrict to income (positive amounts) or expenses (negative amounts). A summary covers exactly one direction; call the tool twice to compare.
end_date	string | null		Inclusive upper bound, ISO 8601 (YYYY-MM-DD). Default: null. Examples: "2024-03-15".
group_by	"none" | "category" | "month" | "both"		Aggregation key. none returns a single row spanning all matched transactions; category groups by category id; month groups by calendar month (YYYY-MM); both groups by (category id, month) pairs. Each summary row reports categoryId and/or month accordingly. Default: "category".
max_amount	number | null		Inclusive upper bound on the transaction amount. Amounts are signed: expenses are negative, income is positive. Combined with direction, both filters are applied. Default: null.
min_amount	number | null		Inclusive lower bound on the transaction amount. Amounts are signed: expenses are negative, income is positive. Combined with direction, both filters are applied. Default: null.
start_date	string | null		Inclusive lower bound, ISO 8601 (YYYY-MM-DD). Default: null. Examples: "2024-03-15".

Raw JSON Schema

{
  "additionalProperties": false,
  "properties": {
    "account_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Restrict to transactions on these account.id values (from get-accounts)."
    },
    "category_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Restrict to these category ids (the `id` field from get-categories)."
    },
    "direction": {
      "description": "Restrict to income (positive amounts) or expenses (negative amounts). A summary covers exactly one direction; call the tool twice to compare.",
      "enum": [
        "Income",
        "Expenses"
      ],
      "type": "string"
    },
    "end_date": {
      "anyOf": [
        {
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive upper bound, ISO 8601 (YYYY-MM-DD).",
      "examples": [
        "2024-03-15"
      ]
    },
    "group_by": {
      "default": "category",
      "description": "Aggregation key. `none` returns a single row spanning all matched transactions; `category` groups by category id; `month` groups by calendar month (YYYY-MM); `both` groups by (category id, month) pairs. Each summary row reports `categoryId` and/or `month` accordingly.",
      "enum": [
        "none",
        "category",
        "month",
        "both"
      ],
      "type": "string"
    },
    "max_amount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive upper bound on the transaction amount. Amounts are signed: expenses are negative, income is positive. Combined with `direction`, both filters are applied."
    },
    "min_amount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive lower bound on the transaction amount. Amounts are signed: expenses are negative, income is positive. Combined with `direction`, both filters are applied."
    },
    "start_date": {
      "anyOf": [
        {
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Inclusive lower bound, ISO 8601 (YYYY-MM-DD).",
      "examples": [
        "2024-03-15"
      ]
    }
  },
  "required": [
    "direction"
  ],
  "type": "object"
}

Output

Field	Type	Required	Description
period	TransactionsSummaryPeriod	✓	Date range covered by the aggregation.
summary	array<TransactionsSummaryGroup>	✓	One entry per aggregation key value.
total	number	✓	Sum across all groups in the summary.

period — TransactionsSummaryPeriod

Date range covered by the aggregation.

Field	Type	Required	Description
endDate	string	✓	Inclusive upper bound, ISO 8601 (YYYY-MM-DD). Examples: "2024-03-31".
startDate	string	✓	Inclusive lower bound, ISO 8601 (YYYY-MM-DD). Examples: "2024-03-01".

summary[] — TransactionsSummaryGroup

One row of an aggregated transactions summary.

Field	Type	Required	Description
averageAmount	number	✓	Mean transaction amount within this group.
categoryId	string | null		Category id when the request grouped by category or both; null otherwise. Resolve to a name via get-categories. Default: null.
month	string | null		ISO 8601 month (YYYY-MM) when the request grouped by month or both; null otherwise. Default: null. Examples: "2024-03".
totalAmount	number	✓	Sum of transaction amounts in this group.
transactionCount	integer	✓	Number of transactions contributing to this group.

Raw JSON Schema

{
  "description": "Aggregated transactions summary",
  "properties": {
    "period": {
      "description": "Date range covered by the aggregation.",
      "properties": {
        "endDate": {
          "description": "Inclusive upper bound, ISO 8601 (YYYY-MM-DD).",
          "examples": [
            "2024-03-31"
          ],
          "type": "string"
        },
        "startDate": {
          "description": "Inclusive lower bound, ISO 8601 (YYYY-MM-DD).",
          "examples": [
            "2024-03-01"
          ],
          "type": "string"
        }
      },
      "required": [
        "startDate",
        "endDate"
      ],
      "type": "object"
    },
    "summary": {
      "description": "One entry per aggregation key value.",
      "items": {
        "description": "One row of an aggregated transactions summary.",
        "properties": {
          "averageAmount": {
            "description": "Mean transaction amount within this group.",
            "type": "number"
          },
          "categoryId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Category id when the request grouped by `category` or `both`; null otherwise. Resolve to a name via get-categories."
          },
          "month": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "ISO 8601 month (YYYY-MM) when the request grouped by `month` or `both`; null otherwise.",
            "examples": [
              "2024-03"
            ]
          },
          "totalAmount": {
            "description": "Sum of transaction amounts in this group.",
            "type": "number"
          },
          "transactionCount": {
            "description": "Number of transactions contributing to this group.",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "totalAmount",
          "transactionCount",
          "averageAmount"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "total": {
      "description": "Sum across all groups in the summary.",
      "type": "number"
    }
  },
  "required": [
    "summary",
    "period",
    "total"
  ],
  "type": "object"
}