Period cost summary with optional preceding-window comparison

GET

/api/v1/costs/summary

const url = 'https://example.com/api/v1/costs/summary?groupBy=service';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://example.com/api/v1/costs/summary?groupBy=service'

Period totals by grouping key for the requested [start, end] window, plus an optional preceding-window comparison computed server-side. groupBy semantics and validation match /api/v1/costs/daily (service / provider / allocation; allocation unconfigured → 400; malformed rules → 500). All money values are exact decimal strings (never floats). The response total equals /api/v1/costs/daily’s period total for identical params. Keys are ordered total-desc, then key-asc. Preceding window: prevEnd = start − 1 day, prevStart = prevEnd − (end − start). The selected currency is pinned to BOTH windows. ALL previous-window fields (previousTotal, previousStart, previousEnd, and every keys[].previousTotal / keys[].delta) are ABSENT together — never null or “” — when the preceding window is UNDEFINED: (i) start or end is unbounded/empty; (ii) the current window is empty (there are no keys to compare); or (iii) the preceding-window query returns zero cost rows in the selected currency. Never emit previousTotal “0” for a data-empty preceding window. A store error from either window is a 500. When the preceding window is DEFINED, every key carries delta = total − previousTotal (exact decimal.Sub); keys absent from the previous window omit previousTotal while delta equals total (previousTotal-absence alone marks newness). “Gone” keys (present only in the previous window) are out of scope for this version. Empty CURRENT window: total “0”, keys [] (never null). No share field — client Number() geometry only.

Parameters

Query Parameters

start

string format: date

Inclusive first calendar day (UTC) of the CURRENT window. Defaults to the full range of stored data. Unbounded start makes the preceding window undefined.

end

string format: date

Inclusive last calendar day (UTC) of the CURRENT window. Defaults to the full range of stored data. Unbounded end makes the preceding window undefined.

groupBy

string

default: service

Allowed values: service provider allocation

Cost grouping dimension (same set as /api/v1/costs/daily).

currency

string

/^[A-Z]{3}$/

Optional three-letter uppercase billing currency whose summary to return. Omit to use the alphabetically-first currency in the current window.

Responses

200

Period cost summary for the requested window.

application/json

object

currency

required

Billing currency of this response’s summary (FOCUS BillingCurrency): the currency query parameter when provided, otherwise the alphabetically-first currency in the current window, or “” when the window is empty.

string

currencies

required

All billing currencies with cost rows in the current window, sorted ascending. This is the source for a currency selector and is [] (never null) when the window is empty.

Array<string>

total

required

Period total for the current window as a decimal string. Equals /api/v1/costs/daily’s period total for identical params. “0” when the current window is empty.

string

previousTotal

Period total of the preceding window as a decimal string. Present only when the preceding window is defined (see path description); omitted entirely otherwise — never null or “0” for an undefined window.

string

previousStart

Inclusive first day of the preceding window. Present exactly when previousTotal is present.

string format: date

previousEnd

Inclusive last day of the preceding window. Present exactly when previousTotal is present.

string format: date

keys

required

Per-key period totals for the current window, ordered total-desc then key-asc. Never null; [] when the current window is empty. Gone keys (previous-only) are out of scope.

Array<object>

object

key

required

Grouping key (ServiceName / ServiceProviderName / allocation label).

string

total

required

Period total for this key in the current window, as a decimal string.

string

previousTotal

Period total for this key in the preceding window. Present only when the preceding window is defined AND the key had cost there; omitted for new keys (delta then equals total) and when the window is undefined.

string

delta

Exact total − previousTotal (decimal.Sub). Present on EVERY key when the preceding window is defined; omitted on every key when undefined. For a new key (no previousTotal), delta equals total.

string

Example

{
  "currency": "USD",
  "currencies": [
    "EUR",
    "USD"
  ],
  "total": "964050.632653589793238462",
  "previousTotal": "120000.50",
  "previousStart": "2025-12-13",
  "previousEnd": "2026-01-11",
  "keys": [
    {
      "key": "Amazon Web Services",
      "total": "3141.592653589793238462",
      "previousTotal": "2800.00",
      "delta": "341.592653589793238462"
    }
  ]
}

400

Invalid start date, end date, groupBy value, or currency shape; or groupBy=allocation was requested but no allocation rules are configured or the rules file was not found.

text/plain

string

500

The cost query failed, including an unreadable, malformed, or invalid allocation rules file.

text/plain

string