--- name: "books_report" area: "books" title: "Run a report" price: "free" method: "POST" url: "https://api.conecto.chat/v1/tools/books_report" mcp_server: "https://api.conecto.chat/mcp/books" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/books/books_report" --- # Run a report (`books_report`) A report: profit and loss, balance sheet, trial balance, ledger, tax, the VAT or OSS return, the cash flow ahead or a snapshot of the business. A report in the base currency. profit_and_loss and tax cover from-to (default: this fiscal year so far); balance_sheet and trial_balance are as of to (default today); general_ledger lists each account's lines from-to with running balances (one account, or all, paged); oss is a quarter's sales to consumers in other EU countries for the One Stop Shop return, per country and VAT rate in euros (quarter, default the last one ended; no books needed); reconciliation holds each bank account's books against the closing balance its latest statement on or before to stated: reconciled, to_match (statement lines and entries still to pair explain the difference) or off (unexplained). Like Xero's: profit_and_loss with compare adds columns for earlier months, quarters or years; cash_summary shows the money accounts at the start and end of from-to and what came in and went out, by account; executive_summary (default this month so far) gives cash, profit, margins, what is owed both ways, debtor and creditor days and invoices issued, against the same days a month before; budget_variance holds a budget (books_save_budget) against the actual figures for the months from-to touches; vat_return gives from-to by the boxes of the VAT return the business files itself, Germany's advance return by Kennzahl or the UK's nine boxes (country, default the business's), with what the books can't tell yet. Like Xero's short-term cash flow, cash_forecast projects the money accounts `days` ahead (default 30, up to 180) from open invoices and bills on their due, expected or planned dates and what repeating templates will make, by day and week, with the lowest point and the overdue invoices and bills it leaves out until they have a date to come (each with the id that invoices_set_expected_date or purchasing_set_planned_date takes). snapshot is the year so far (default) against the same days a year before: profit, margins, income and expenses by month, the largest costs, the balance sheet, cash, and the average days from an invoice's or a bill's date to the payment that settled it, for those paid in the period. To show a person, put it in a view (view_show). Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing. ## Use it when Someone asks how the business is doing, what it owns and owes, how much tax is due, what goes in the VAT return or the quarterly OSS return, or how much cash there will be in a few weeks. - For a page that shows the report to a person, use [view_show](https://conecto.chat/tools/views/view_show.md). ## Say this to your agent > How much profit have we made so far this year? ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `report` | string | yes | | `"profit_and_loss"`, `"balance_sheet"`, `"trial_balance"`, `"general_ledger"`, `"tax"`, `"oss"`, `"reconciliation"`, `"cash_summary"`, `"executive_summary"`, `"budget_variance"`, `"vat_return"`, `"cash_forecast"`, `"snapshot"` | | | `from` | string | no | YYYY-MM-DD (matches ^\\d{4}-\\d{2}-\\d{2}$) | | | | `to` | string | no | YYYY-MM-DD (matches ^\\d{4}-\\d{2}-\\d{2}$) | | | | `account` | string | no | An account code from the chart, e.g. "6600". 1 to 20 characters. | | | | `compare` | string | no | For profit_and_loss: add columns for the same days `periods` months, quarters or years before. | `"month"`, `"quarter"`, `"year"` | | | `periods` | integer | no | With compare; default 1. 1 to 11. | | | | `budget` | string | no | For budget_variance: the budget's name (books_list_budgets). Up to 80 characters. | | | | `by_tracking` | string | no | For profit_and_loss: a tracking category to split by, one column per option and one for what is not tracked. Up to 60 characters. | | | | `tracking` | object | no | For profit_and_loss: only lines with these options, e.g. {"Department": "Service"}. | | | | `quarter` | string | no | For oss: like 2026-Q3. Matches ^\\d{4}-[Qq][1-4]$. | | | | `country` | string | no | For vat_return: whose form. Default the business's country. | `"DE"`, `"GB"` | | | `days` | integer | no | For cash_forecast: how many days ahead. 1 to 180. | | `30` | | `limit` | integer | no | 1 to 2,000. | | `500` | | `offset` | integer | no | At least 0. | | `0` | ## Example Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. MCP: call `books_report` on the MCP server `https://api.conecto.chat/mcp/books` with these arguments: ```json { "report": "profit_and_loss", "from": "2026-01-01", "to": "2026-10-31" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/books_report \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"report": "profit_and_loss", "from": "2026-01-01", "to": "2026-10-31"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "books_report", "status": "succeeded", "replayed": false, "cost_usd": "$0.00", "balance_usd": "$19.75", "result": { "report": "profit_and_loss", "from": "2026-01-01", "to": "2026-10-31", "currency": "EUR", "income": [ { "account": "4000", "name": "Sales", "amount": "1890.00" } ], "total_income": "1890.00", "expenses": [ { "account": "6800", "name": "Utilities and phone", "amount": "200.00" } ], "total_expenses": "200.00", "net_profit": "1690.00" } } ``` `result`: The report's name, period and currency, and its sections with accounts and totals: for profit and loss the income, the expenses and the net profit; for vat_return each box with the form's own words, its base and tax, and what the books can't tell yet; for oss the rows per country and VAT rate in euros, corrections of earlier quarters and the VAT in all; for cash_forecast the balance by day and week, the lowest point and the overdue invoices and bills it leaves out. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `no_books` | 409 | The business keeps no books yet. | Set them up with books_setup (base currency, start date). | | `not_found` | 404 | No account, tax, entry or file of the books has that code, name or id. | Check the codes with books_list_accounts and the taxes with books_get. | | `archived` | 409 | The account or tax is archived. | Use another one, or un-archive it with books_save_accounts. | | `invalid_input` | 400 | A date is not a date like 2026-10-01, or from is after to. | Fix the date. | | `invalid_input` | 400 | For oss: the quarter is not like 2026-Q3, or the business is not in the EU; for vat_return: no form for the business's country (DE and GB so far). | Give a quarter like 2026-Q3, or country; set the business's country with invoices_set_profile. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [books_setup](https://conecto.chat/tools/books/books_setup.md): Starts the business's double-entry books (currency, start date, chart of accounts) or changes their settings. $0.001 a call. - [books_get](https://conecto.chat/tools/books/books_get.md): The books' settings: currency, start date, fiscal year, locked period, roles, payment accounts, taxes, and what is waiting. Free up to 1,000,000 reads a month. - [books_list_accounts](https://conecto.chat/tools/books/books_list_accounts.md): Every account with its code, type, role and balance on a day. Free up to 1,000,000 reads a month. - [books_save_accounts](https://conecto.chat/tools/books/books_save_accounts.md): Adds accounts or changes them, matched by code: name, type, description, code, role or archived. $0.001 a call. - [books_save_tax](https://conecto.chat/tools/books/books_save_tax.md): Adds or changes a tax rate the books use (VAT, GST, sales tax), matched by name. $0.001 a call. - [books_record_expense](https://conecto.chat/tools/books/books_record_expense.md): Books a cost the business paid, with its tax split off and the receipt attached. $0.01 a call. - [books_record_entry](https://conecto.chat/tools/books/books_record_entry.md): Books a journal entry of two or more balancing lines, for whatever the other tools do not cover. $0.01 a call. - [books_attach_receipt](https://conecto.chat/tools/books/books_attach_receipt.md): Attaches a receipt from the file store to an entry that has none. $0.01 a call. - [books_reverse_entry](https://conecto.chat/tools/books/books_reverse_entry.md): Undoes an entry by booking its mirror image; entries are never edited or deleted. $0.01 a call. - [books_list_entries](https://conecto.chat/tools/books/books_list_entries.md): Entries, newest first, with their lines, by dates, account, source or text. Free up to 1,000,000 reads a month. - [books_import_bank](https://conecto.chat/tools/books/books_import_bank.md): Reads a bank statement from the file store (CSV, CAMT.053 or OFX) onto a bank account, skipping lines imported before. Free. - [books_bank_lines](https://conecto.chat/tools/books/books_bank_lines.md): Imported bank lines (by default the ones still to match), each with up to three suggestions of what it was. Free up to 1,000,000 reads a month. - [books_match_bank_lines](https://conecto.chat/tools/books/books_match_bank_lines.md): Says what bank lines were: entries already booked, invoices or bills they pay, an account to book them to, or nothing to book. $0.02 per bank line matched. - [books_save_bank_rule](https://conecto.chat/tools/books/books_save_bank_rule.md): Saves a bank rule, like Xero's: which new bank lines it matches and how they are booked, to one account or split by percent, each part with its own tax. $0.001 a call. - [books_list_bank_rules](https://conecto.chat/tools/books/books_list_bank_rules.md): Lists the bank rules in the order they are tried, with where they book and how often they were used. Free up to 1,000,000 reads a month. - [books_apply_bank_rules](https://conecto.chat/tools/books/books_apply_bank_rules.md): Books every new bank line a rule matches, each by the first rule that matches. $0.02 per bank line booked. - [books_delete_bank_rule](https://conecto.chat/tools/books/books_delete_bank_rule.md): Deletes a bank rule; what it booked stays booked. Free. - [books_save_tracking](https://conecto.chat/tools/books/books_save_tracking.md): Saves a tracking category with its options, like Xero's: a department, a region or a project line that any line of the books can carry. $0.001 a call. - [books_list_tracking](https://conecto.chat/tools/books/books_list_tracking.md): Lists the tracking categories and their options. Free up to 1,000,000 reads a month. - [books_save_budget](https://conecto.chat/tools/books/books_save_budget.md): Saves a budget per income and expense account and month, like Xero's budget manager: amounts, monthly or yearly. $0.001 a call. - [books_list_budgets](https://conecto.chat/tools/books/books_list_budgets.md): Lists the budgets with every line's monthly amounts and total. Free up to 1,000,000 reads a month. - [books_delete_budget](https://conecto.chat/tools/books/books_delete_budget.md): Deletes a budget; the books don't change. Free. - [books_repay_claims](https://conecto.chat/tools/books/books_repay_claims.md): Pays someone back for costs they paid with their own money (expense claims), like Xero's, with a SEPA file when asked. $0.01 a call. - [books_list_claims](https://conecto.chat/tools/books/books_list_claims.md): Lists expense claims: what people paid for the business privately, and what each is owed. Free up to 1,000,000 reads a month. - [books_save_asset](https://conecto.chat/tools/books/books_save_asset.md): Registers a fixed asset (a van, a machine) and how it depreciates, like Xero's: straight line, declining balance, at once or not at all. $0.001 a call. - [books_list_assets](https://conecto.chat/tools/books/books_list_assets.md): The fixed asset register: each asset's cost, accumulated depreciation and book value, what a run would book now, and the register held against the books. Free up to 1,000,000 reads a month. - [books_depreciate](https://conecto.chat/tools/books/books_depreciate.md): Books the depreciation of every registered asset through a month's end, one entry a month, like Xero's run depreciation; or undoes it after a date. $0.01 a call. - [books_dispose_asset](https://conecto.chat/tools/books/books_dispose_asset.md): Sells or writes off a fixed asset, like Xero's dispose: depreciation to the day it goes, then its cost, the price and the gain or loss. $0.01 a call. - [books_delete_asset](https://conecto.chat/tools/books/books_delete_asset.md): Takes an asset registered by mistake out of the register; the books don't change. Free. - [books_lock](https://conecto.chat/tools/books/books_lock.md): Locks the books through a date, so nothing new is booked on or before it; null unlocks. $0.001 a call. - [books_close_year](https://conecto.chat/tools/books/books_close_year.md): Closes a fiscal year for good: nothing is booked on or before its last day again, and it can't be undone. $0.001 a call. - [books_export](https://conecto.chat/tools/books/books_export.md): A CSV of the journal or the accounts, a DATEV Buchungsstapel for a German tax adviser or a French FEC, with a download link. $0.001 a call.