Summarise forecasts

Totals over dated forecasts per period bucket and at most one more dimension. Give period, or both from and to.

amount totals what was planned and remaining_amount the part not yet matched by transactions. Every status counts unless status narrows it, so a realised forecast still adds to amount and adds nothing to remaining_amount. Amounts convert to currency at the rate of each forecast’s own date. Buckets are calendar aligned and clipped to the window. totals covers the whole window.

Grouped rows are ordered by absolute amount, largest first. A period keeps at most 50 groups; the rest fold into one row labelled other. Forecasts with no counterparty or no label fall in a none row, and a forecast with several labels counts once per label. Here category_id also covers subcategories.

GET

forecasts

summary

Summarise forecasts

curl --request GET \
  --url https://api.thinkout.io/v1/forecasts/summary \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thinkout.io/v1/forecasts/summary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

using RestSharp;


var options = new RestClientOptions("https://api.thinkout.io/v1/forecasts/summary");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "object": "forecast_summary",
  "period": {
    "from": "2023-12-25",
    "to": "2023-12-25",
    "macro": "this_month",
    "interval": "month"
  },
  "conversion": {
    "applied": true,
    "currency": "RON",
    "basis": "transaction_date"
  },
  "group_by": "category",
  "has_data": true,
  "totals": {
    "currency": "RON",
    "amount": "-1250.00",
    "remaining_amount": "-1250.00",
    "count": 123
  },
  "data": [
    {
      "period_start": "2023-12-25",
      "period_end": "2023-12-25",
      "group": {
        "dimension": "category",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "label": "Telecom"
      },
      "currency": "RON",
      "amount": "-1250.00",
      "remaining_amount": "-1250.00",
      "count": 123
    }
  ]
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "direction must be 'inflow' or 'outflow'",
    "param": "direction",
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

{
  "error": {
    "type": "authentication",
    "code": "unauthorized",
    "message": "Missing, malformed, unknown or revoked API key",
    "param": null,
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

{
  "error": {
    "type": "authentication",
    "code": "forbidden",
    "message": "The API is not included in this company's ThinkOut plan. Contact support@thinkout.io to enable it.",
    "param": null,
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "too_many_groups",
    "message": "Grouping by counterparty over this period produces 1240 groups. The maximum is 1000. Narrow the period or the filters.",
    "param": "group_by",
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

{
  "error": {
    "type": "rate_limit",
    "code": "rate_limited",
    "message": "Too many requests",
    "param": null,
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

Authorizations

Authorization

string

header

required

A workspace API key created in ThinkOut settings. One key reads one workspace.

Query Parameters

period

enum<string>

A named window, resolved against the workspace's local day and echoed in the response. Takes precedence over from and to. A named window resolved on the server. last_30_days and last_90_days end today and include it; last_12_months starts the day after today minus twelve months. next_month, next_quarter and next_year cover the whole next calendar month, quarter or year.

Available options:

this_month,

last_month,

this_quarter,

last_quarter,

this_year,

last_year,

month_to_date,

quarter_to_date,

year_to_date,

last_30_days,

last_90_days,

last_12_months,

next_month,

next_quarter,

next_year

from

string<date>

First day of the window, inclusive. Required with to unless period is given.

string<date>

Last day of the window, inclusive. Required with from unless period is given.

interval

enum<string>

default:month

The period bucket rows are grouped into. A period bucket for report rows.

Available options:

day,

week,

month

group_by

enum<string>

A second dimension to group by, alongside the period bucket. Omit it for one row per period. As GroupDimension, plus forecast status. Forecasts have no account.

Available options:

category,

counterparty,

label,

activity,

direction,

status

currency

string

Currency to report in. Defaults to the workspace currency. An unknown code is rejected. ISO 4217 alphabetic currency code.

Pattern: ^[A-Z]{3}$

Example:

"RON"

category_id

string<uuid>[]

Only rows in these categories. Comma-separated for several. On /transactions this also matches a split transaction whose pieces are in one of them. Subcategories are included only on the summaries.

label_id

string<uuid>[]

Only rows carrying at least one of these labels. Comma-separated for several.

counterparty_id

string<uuid>[]

Only rows attributed to these counterparties. Comma-separated for several.

direction

enum<string>

Whether money comes in or goes out. On a transaction or forecast it follows the sign of amount.

Available options:

inflow,

outflow

activity

enum<string>[]

Only rows whose category sits in these cash flow statement sections. Comma-separated for several.

Cash flow statement section the category belongs to.

Available options:

operating,

investing,

financing

status

enum<string>

realised is complete. partial has matched transactions. overdue is dated before today with none. planned is dated today or later with none.

Available options:

planned,

overdue,

partial,

realised

Response

The summary.

object

string

required

Allowed value: "forecast_summary"

period

object

required

The window actually computed.

Show child attributes

conversion

object

required

What was done to make amounts comparable.

Show child attributes

group_by

enum<string> | null

required

As GroupDimension, plus forecast status. Forecasts have no account.

Available options:

category,

counterparty,

label,

activity,

direction,

status

has_data

boolean

required

false when no forecast matched.

totals

object

required

The whole window added up, over the same forecasts as the rows.

Show child attributes

data

object[]

required

Show child attributes

Summarise forecasts

curl --request GET \
  --url https://api.thinkout.io/v1/forecasts/summary \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thinkout.io/v1/forecasts/summary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

using RestSharp;


var options = new RestClientOptions("https://api.thinkout.io/v1/forecasts/summary");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "object": "forecast_summary",
  "period": {
    "from": "2023-12-25",
    "to": "2023-12-25",
    "macro": "this_month",
    "interval": "month"
  },
  "conversion": {
    "applied": true,
    "currency": "RON",
    "basis": "transaction_date"
  },
  "group_by": "category",
  "has_data": true,
  "totals": {
    "currency": "RON",
    "amount": "-1250.00",
    "remaining_amount": "-1250.00",
    "count": 123
  },
  "data": [
    {
      "period_start": "2023-12-25",
      "period_end": "2023-12-25",
      "group": {
        "dimension": "category",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "label": "Telecom"
      },
      "currency": "RON",
      "amount": "-1250.00",
      "remaining_amount": "-1250.00",
      "count": 123
    }
  ]
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "direction must be 'inflow' or 'outflow'",
    "param": "direction",
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

{
  "error": {
    "type": "authentication",
    "code": "unauthorized",
    "message": "Missing, malformed, unknown or revoked API key",
    "param": null,
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

{
  "error": {
    "type": "authentication",
    "code": "forbidden",
    "message": "The API is not included in this company's ThinkOut plan. Contact support@thinkout.io to enable it.",
    "param": null,
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "too_many_groups",
    "message": "Grouping by counterparty over this period produces 1240 groups. The maximum is 1000. Narrow the period or the filters.",
    "param": "group_by",
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

{
  "error": {
    "type": "rate_limit",
    "code": "rate_limited",
    "message": "Too many requests",
    "param": null,
    "request_id": "0HNF8K3QJL2VM:00000001"
  }
}

Getting started

MCP

REST API

API reference

Summarise forecasts

Authorizations

Query Parameters

Response