Method

report.run

Run a report on the open book: the report result, with exact figures.

Runs a report on the open book and returns its result: tables, charts and text, with exact figures (every amount is a rational as well as a display string). Name the report by name or GUID, and change options with options, as {"Section": {"Name": value}}, only the ones you want; report.options lists them. It reads the book only: it works on a read-only book and never makes one dirty.

"Today" and relative dates such as end-this-month follow the session's clock, or now if you give it. Numbers and dates are formatted in the Configuration's locale, or locale. A saved configuration is run by its name or GUID, and options are applied over its saved ones. For HTML use report.export; each report has its own Page with an example.

A report that cannot show anything says so in a warning block instead of failing, such as No accounts selected or No data. Unknown options, options of the wrong type and unknown reports are errors; a name that matches a template and a saved configuration is a conflict that lists the matches.

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash, at 2024-03-15T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"report.run","params":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "title": " Balance Sheet 12/31/78",
    "report": {
      "name": "Balance Sheet",
      "…": "…"
    },
    "sections": [
      {
        "blocks": [
          {
            "kind": "table",
            "rows": [
              "…",
              "…",
              "…",
              "…",
              "…",
              "…",
              {
                "role": "total",
                "cells": [
                  {
                    "text": "Total Assets",
                    "…": "…"
                  },
                  {
                    "display": "$3,057.80",
                    "…": "…"
                  }
                ],
                "…": "…"
              },
              "…"
            ],
            "…": "…"
          },
          "…"
        ],
        "…": "…"
      },
      "…"
    ],
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"report.run","params":{"report":"Transaction Report"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "title": "Transaction Report",
    "sections": [
      {
        "blocks": [
          {
            "kind": "warning",
            "title": "No accounts selected",
            "…": "…"
          },
          "…"
        ],
        "…": "…"
      },
      "…"
    ],
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"report.run","params":{"report":"Balance Sheet","options":{"General":{"Colour":"red"}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": 3002,
    "message": "option General/Colour: unknown option",
    "data": {
      "section": "General",
      "name": "Colour",
      "reason": "unknown option",
      "help": "error/report-option"
    }
  }
}

Request:

{"jsonrpc":"2.0","id":4,"method":"report.run","params":{"report":"Balance Shet"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": 2000,
    "message": "report Balance Shet not found",
    "data": {
      "kind": "report",
      "id": "Balance Shet",
      "help": "error/not-found"
    }
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
report.run {"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}
report.run {"report":"Transaction Report"}
report.run {"report":"Balance Sheet","options":{"General":{"Colour":"red"}}}
report.run {"report":"Balance Shet"}
EOF

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 3002,
    "message": "option General/Colour: unknown option",
    "data": {
      "section": "General",
      "name": "Colour",
      "reason": "unknown option",
      "help": "error/report-option"
    }
  }
}

MCP tool call

Tool call:

{"name":"report.run","arguments":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}}

Result:

{
  "structuredContent": {
    "title": " Balance Sheet 12/31/78",
    "report": {
      "name": "Balance Sheet",
      "…": "…"
    },
    "sections": [
      {
        "blocks": [
          {
            "kind": "table",
            "rows": [
              "…",
              "…",
              "…",
              "…",
              "…",
              "…",
              {
                "role": "total",
                "cells": [
                  {
                    "text": "Total Assets",
                    "…": "…"
                  },
                  {
                    "display": "$3,057.80",
                    "…": "…"
                  }
                ],
                "…": "…"
              },
              "…"
            ],
            "…": "…"
          },
          "…"
        ],
        "…": "…"
      },
      "…"
    ],
    "…": "…"
  }
}

Tool call:

{"name":"report.run","arguments":{"report":"Transaction Report"}}

Result:

{
  "structuredContent": {
    "title": "Transaction Report",
    "sections": [
      {
        "blocks": [
          {
            "kind": "warning",
            "title": "No accounts selected",
            "…": "…"
          },
          "…"
        ],
        "…": "…"
      },
      "…"
    ],
    "…": "…"
  }
}

Tool call:

{"name":"report.run","arguments":{"report":"Balance Sheet","options":{"General":{"Colour":"red"}}}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 3002,
      "name": "report-option",
      "message": "option General/Colour: unknown option",
      "data": {
        "section": "General",
        "name": "Colour",
        "reason": "unknown option",
        "help": "error/report-option"
      }
    }
  }
}

Tool call:

{"name":"report.run","arguments":{"report":"Balance Shet"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2000,
      "name": "not-found",
      "message": "report Balance Shet not found",
      "data": {
        "kind": "report",
        "id": "Balance Shet",
        "help": "error/not-found"
      }
    }
  }
}

Effect: read.

Params

Params of report.run.

  • report (ReportRef, required): The report.
  • options (ReportOptions or null): Changes over the template's defaults, or over the saved configuration's values.
  • now (Timestamp or null): The time to run the report for; by default the session's clock. Relative dates and "today" follow it.
  • locale (string or null): The Locale to format numbers and dates in for this run: a supported POSIX locale name (fr_FR, C) or environment; by default the Configuration's locale setting.

Result

A finished report result, as report.run returns it.

  • version (string, required): The result's version: [RESULT_VERSION].
  • report (ReportIdentity, required): The template and saved configuration that produced it.
  • title (string, required): The document title (gnc:html-document-set-title!): the HTML <title> and, without a headline, the heading.
  • headline (string or null): A heading when it differs from the title (gnc:html-document-set-headline!).
  • now (string (date-time), required): The time the report was run for.
  • options (object, required): Every option's value, in wire form, so the result says exactly what produced it.
  • sections (array of Section, required): The sections, in order.
  • log (array of LogEntry, required): The report log: what the script printed.
  • export (array of array of ExportCell or null or null): The rows of the report's export, when the run was for an export the template offers (report.exportCsv): GnuCash's export string before it is joined (gnc:html-document-set-export-string). Absent otherwise.
  • exportError (string or null): Why the run for an export has nothing to export, as the script gave it (gnc:html-document-set-export-error, 5.17:gnucash/report/trep-engine.scm:2524): "No splits found". Absent otherwise.
  • css (string or null): The report's own CSS, which a page appends after the style sheet's (gnc:html-document-set-style-text!, 5.17:gnucash/report/reports/standard/invoice.scm:795) (v0.6). Never text the CSS template refuses (design/reports.md §8): the host leaves that out and says so in the log. Absent when the report sets none.