Aggregations

Retrieve total

Calculates one signed total for the requested category and its descendants.

Check the category’s point_in_time field from GET /categories before choosing date parameters. Periodic categories (point_in_time: false), such as income-statement and cash-flow categories, require start_date and end_date. Point-in-time categories (point_in_time: true), such as balance-sheet categories, require date and reject start_date and end_date.

Existing integrations may continue using the deprecated month contract. Periodic categories accept start_month and end_month; point-in-time categories accept only end_month. Month parameters use YYYY-MM, retain whole-month behavior, and cannot be combined with full-date parameters. Responses include both representations so clients can migrate independently.

Full dates use YYYY-MM-DD calendar dates in America/Los_Angeles (Pacific Time). Periodic totals include exactly start_date through end_date, inclusive. Point-in-time totals are cumulative through the exact date. Behavioral breaking change: full-date category totals previously ignored the day and selected whole months. To keep whole-month totals, use the first and last calendar days or the deprecated month parameters. Assets use debit minus credit. All other categories use credit minus debit.

Whole months use whole-month rollups; the current month’s first day through today in Pacific Time uses fresh MTD rollups. Other partial months, including a midmonth start, use slower raw-entry reads for only those months. Stale or unfilled MTD falls back to raw entries. Month-aligned month-to-date and year-to-date requests remain fast when MTD is fresh.

merchant is an exact, case-sensitive match. A blank value means all merchants.

Response dates are the exact boundaries used. refreshed_at covers the entire result: the maximum contributing rollup timestamp, including MTD, or current as of the call when any portion reads live raw entries, even with no matching raw entries. It is null only when no contributing timestamp or live raw read is available. Rollups may lag new activity.

The API rejects period and department_id. It ignores other unknown query parameters.

GET

aggregations

total

Retrieve total

curl --request GET \
  --url https://app.finta.com/api/v1/aggregations/total \
  --header 'Authorization: Bearer <token>'

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

fetch('https://app.finta.com/api/v1/aggregations/total', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.finta.com/api/v1/aggregations/total",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.finta.com/api/v1/aggregations/total"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/aggregations/total")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "total",
  "category_id": "cat_o5p6q7r8s9t0u1",
  "merchant": "AWS",
  "start_month": "2026-01",
  "end_month": "2026-03",
  "start_date": "2026-01-15",
  "end_date": "2026-03-20",
  "date": null,
  "point_in_time": false,
  "total_cents": -182340,
  "currency": "USD",
  "debit_cents": 182340,
  "credit_cents": 0,
  "refreshed_at": 1786992120
}

Authorizations

Authorization

string

header

required

API key prefixed with finta_

Query Parameters

category_id

string

required

A cat_ ID returned by GET /categories.

Pattern: ^cat_[A-Za-z0-9]+$

start_month

string

Deprecated first whole month for a periodic category, as YYYY-MM. Includes its first calendar day in Pacific Time. Use with end_month, not with full-date parameters.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

end_month

string

Deprecated last whole month for a periodic category or cutoff month for a point-in-time category, as YYYY-MM. Includes its last calendar day in Pacific Time, even for the current month. Do not combine with full-date parameters.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

start_date

string<date>

Exact first included calendar date for a periodic category, as YYYY-MM-DD in Pacific Time. Required when point_in_time is false and rejected when it is true. A midmonth start uses a slower raw-entry read for that partial month.

end_date

string<date>

Exact last included calendar date for a periodic category, as YYYY-MM-DD in Pacific Time. Required when point_in_time is false and rejected when it is true. Month-start through today uses fresh MTD rollups; other partial-month cutoffs use slower raw-entry reads.

date

string<date>

Exact inclusive cutoff calendar date for a point-in-time category, as YYYY-MM-DD in Pacific Time. Required when point_in_time is true and rejected when it is false. Today uses fresh MTD rollups; other non-month-end cutoffs use a slower raw-entry read for the cutoff month.

merchant

string

Exact, case-sensitive merchant or counterparty name. Blank means all merchants.

Response

The requested total

object

enum<string>

required

Available options:

total

category_id

string

required

The requested public category ID.

Pattern: ^cat_[A-Za-z0-9]+$

Example:

"cat_o5p6q7r8s9t0u1"

merchant

string | null

required

The exact merchant filter, or null when no merchant filter was applied.

Example:

"AWS"

start_month

string | null

required

The calendar month containing the actual periodic start date. Derived from start_date for full-date requests; it does not widen the range to a whole month. Null for point-in-time totals.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

Example:

"2026-01"

end_month

string

required

The calendar month containing the actual periodic end or point-in-time cutoff date. Derived from end_date or date for full-date requests; it does not widen the range to a whole month.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

Example:

"2026-03"

start_date

string<date> | null

required

The actual inclusive periodic start calendar date in Pacific Time. For a legacy month request, this is the first day of start_month. Null when point_in_time is true.

Example:

"2026-01-15"

end_date

string<date> | null

required

The actual inclusive periodic end calendar date in Pacific Time. For a legacy month request, this is the last day of end_month, not clamped to today. Null when point_in_time is true.

Example:

"2026-03-20"

date

string<date> | null

required

The actual inclusive point-in-time cutoff calendar date in Pacific Time. For a legacy month request, this is the last day of end_month, not clamped to today. Null when point_in_time is false.

Example:

null

point_in_time

boolean

required

When true, request the total with date. When false, request it with start_date and end_date.

Example:

false

total_cents

integer

required

Signed total in cents. Assets use debit minus credit; all other categories use credit minus debit.

Example:

-182340

currency

enum<string>

required

ISO 4217 currency code for the total.

Available options:

USD

Example:

"USD"

debit_cents

integer

required

Contributing debit amount in cents before sign calculation.

Example:

182340

credit_cents

integer

required

Contributing credit amount in cents before sign calculation.

Example:

0

refreshed_at

integer | null

required

Unix timestamp covering the entire result, including partial months. For rollup-only reads, the maximum contributing rollup timestamp including MTD. Any live raw-entry portion is current as of the call, even with no matching raw entries. Null only when no contributing timestamp or live raw read is available.

Example:

1786992120

Retrieve total

curl --request GET \
  --url https://app.finta.com/api/v1/aggregations/total \
  --header 'Authorization: Bearer <token>'

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

fetch('https://app.finta.com/api/v1/aggregations/total', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.finta.com/api/v1/aggregations/total",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.finta.com/api/v1/aggregations/total"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.finta.com/api/v1/aggregations/total")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "total",
  "category_id": "cat_o5p6q7r8s9t0u1",
  "merchant": "AWS",
  "start_month": "2026-01",
  "end_month": "2026-03",
  "start_date": "2026-01-15",
  "end_date": "2026-03-20",
  "date": null,
  "point_in_time": false,
  "total_cents": -182340,
  "currency": "USD",
  "debit_cents": 182340,
  "credit_cents": 0,
  "refreshed_at": 1786992120
}

API Reference

Onboarding

Sheets

Taxes

Files

Company

Plans & billing

Team

Categories

Rules

Tags

Departments

Integrations

Inbox

Aggregations

Transactions

Forms

Reconciliation

Journal Entries

Invoices

Parties

Metrics

Reports

Feedback

Tax Credits

Retrieve total

Authorizations

Query Parameters

Response