GET

List business plan goals vs actuals

Scope:accounting:cashflow.read

https://api.holded.com/api/v2/business-plan/goals

Returns Business Plan goals for the authenticated account, one row per accounting account, broken down by month. Each month carries both the `goal` (the target the account set for itself) and the `actual` (what really happened, from the ledger) for the same period, so goal and reality can be compared without a second call. Use when the user wants to compare a client's Business Plan targets against what actually happened, e.g. to prepare a monthly review. Only `tree=profit_and_loss` is supported today; Cashflow goals are not available through this endpoint yet. `start_date` must not be after `end_date`, and the range between them must not exceed 36 months. Returns an empty list, not an error, when the account has no Business Plan configured or no goals exist in the requested range.

Parameters

Query parameters

start_datestring<date>required

Start of the reporting range (inclusive, snapped to the first day of its month)

end_datestring<date>required

End of the reporting range (inclusive — any day within the last desired month)

treestringrequired

Goal tree to query. Only "profit_and_loss" is supported today.

"profit_and_loss"

scenario_idstringoptional

Business Plan scenario to query — see GET /api/v2/business-plan/scenarios. Defaults to the account's main scenario.

accounting_account_idstringoptional

Restrict the response to a single accounting account. Omit to return every account in the tree.

only_with_goalsbooleanoptional= false

When true, excludes accounting accounts with no goal set anywhere in the requested range. Without it, a chart of accounts with few goals mostly returns rows with goal: null — this filters those out before pagination, so pages are not spent on empty accounts.

cursorstringoptional

Opaque cursor for pagination

limitintegeroptional= 50

Maximum number of accounting accounts to return per page. Defaults to 50, maximum 200.

Request

python

import requests

url = "https://api.holded.com/api/v2/business-plan/goals?start_date=2026-01-01&end_date=2026-12-31&tree=profit_and_loss"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

response = requests.get(url, headers=headers)
print(response.json())

Responses

Response

json

{
  "items": [
    {
      "accounting_account_id": "507f1f77bcf86cd799439011",
      "accounting_account_number": 70500001,
      "accounting_account_name": "Ventas",
      "months": [
        {
          "month": "...",
          "goal": "...",
          "actual": "..."
        }
      ]
    }
  ],
  "cursor": "string",
  "has_more": true
}

Success responses

200List of business plan goals vs actuals, by accounting accountapplication/json

object

items[]object[]

accounting_account_idstring

Identifier of the accounting account

accounting_account_numberinteger

Chart of accounts number

accounting_account_namestring

Name of the accounting account

months[]object[]

One entry per month in the requested range, always present even when both goal and actual are empty for that month

cursorstring | null

Opaque cursor pointing to the next page. Pass as `cursor` in the next request. Null when there is no next page.

has_moreboolean

Whether more pages are available after this one

Error responses

400Invalid tree, date range or identifierapplication/json

401Invalid or missing API keyapplication/json

403Insufficient permissionsapplication/json

404Scenario or accounting account not foundapplication/json

429Rate limit exceededapplication/json