Method

budget.get

One budget with its periods, amounts and notes.

Returns one budget with its periods (each with its first and last day), every amount that is set and every note. Give accounts to see only those. A budget amount is either set (even to zero) or unset, which budget.get simply does not list: 0 and nothing are different, because the budget reports roll an unset parent up from its children but not a parent set to zero.

Amounts are in natural signs: an expense budget is positive, an income budget negative. hidden counts amounts and notes beyond the budget's period count, which are kept; orphaned counts those of accounts no longer in the book.

Examples

Example: with a copy of the reports/budget example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"budget.get","params":{"budget":"f0000000000000000000000000000000","accounts":["Root:Expenses"]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "f0000000000000000000000000000000",
    "name": "test budget",
    "numPeriods": 6,
    "periods": [
      {
        "index": 0,
        "startDate": "2024-03-01",
        "endDate": "2024-03-31"
      },
      "…"
    ],
    "amounts": [
      {
        "accountName": "Root:Expenses",
        "period": 1,
        "amount": {
          "num": "30",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 2,
        "amount": {
          "num": "20",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 3,
        "amount": {
          "num": "40",
          "denom": "1"
        },
        "…": "…"
      }
    ],
    "notes": [
      "…"
    ],
    "hidden": {
      "amounts": 0,
      "notes": 0
    },
    "orphaned": {
      "amounts": 0,
      "notes": 0
    },
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash budget.get '{"budget":"f0000000000000000000000000000000","accounts":["Root:Expenses"]}'

It prints:

{
  "guid": "f0000000000000000000000000000000",
  "name": "test budget",
  "numPeriods": 6,
  "periods": [
    {
      "index": 0,
      "startDate": "2024-03-01",
      "endDate": "2024-03-31"
    },
    "…"
  ],
  "amounts": [
    {
      "accountName": "Root:Expenses",
      "period": 1,
      "amount": {
        "num": "30",
        "denom": "1"
      },
      "…": "…"
    },
    {
      "period": 2,
      "amount": {
        "num": "20",
        "denom": "1"
      },
      "…": "…"
    },
    {
      "period": 3,
      "amount": {
        "num": "40",
        "denom": "1"
      },
      "…": "…"
    }
  ],
  "notes": [
    "…"
  ],
  "hidden": {
    "amounts": 0,
    "notes": 0
  },
  "orphaned": {
    "amounts": 0,
    "notes": 0
  },
  "…": "…"
}

MCP tool call

Tool call:

{"name":"budget.get","arguments":{"budget":"f0000000000000000000000000000000","accounts":["Root:Expenses"]}}

Result:

{
  "structuredContent": {
    "guid": "f0000000000000000000000000000000",
    "name": "test budget",
    "numPeriods": 6,
    "periods": [
      {
        "index": 0,
        "startDate": "2024-03-01",
        "endDate": "2024-03-31"
      },
      "…"
    ],
    "amounts": [
      {
        "accountName": "Root:Expenses",
        "period": 1,
        "amount": {
          "num": "30",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 2,
        "amount": {
          "num": "20",
          "denom": "1"
        },
        "…": "…"
      },
      {
        "period": 3,
        "amount": {
          "num": "40",
          "denom": "1"
        },
        "…": "…"
      }
    ],
    "notes": [
      "…"
    ],
    "hidden": {
      "amounts": 0,
      "notes": 0
    },
    "orphaned": {
      "amounts": 0,
      "notes": 0
    },
    "…": "…"
  }
}

Effect: read.

Params

Params of budget.get.

  • budget (Guid, required): The budget.
  • accounts (array of AccountRef or null): List amounts and notes of these accounts only.

Result

A budget.

  • guid (Guid, required): Identity.
  • name (string, required): The name.
  • description (string, required): The description.
  • numPeriods (integer (uint32), required): The number of periods.
  • recurrence (Recurrence, required): The recurrence that gives the periods' dates, as stored.
  • isDefault (boolean, required): True for the default budget.
  • periods (array of PeriodInfo or null): Each period below numPeriods; absent in budget.list.
  • amounts (array of AmountInfo or null): Every set amount of an account in the tree below numPeriods, by account full name then period; absent in budget.list.
  • notes (array of NoteInfo or null): Every note likewise; absent in budget.list.
  • hidden (SlotCounts, required): Amounts and notes kept at or beyond numPeriods.
  • orphaned (SlotCounts, required): Amounts and notes kept for GUIDs that name no account.