Aggregations

List totals

Splits one category’s total into rows by merchant or by month, in one call. Merchant rows across all pages, and periodic month rows, add up to GET /aggregations/total for the same parameters. Point-in-time month rows are closing balances, so don’t add them; the last one matches GET /aggregations/total with date in that month.

group_by=merchant: one row per merchant or counterparty, order=desc by default. Dates follow the category’s rules: start_date and end_date, or date for point-in-time categories.
group_by=month: one row per month, at most 120, in calendar order unless order is given. Always takes start_date and end_date; point-in-time categories return each month’s closing balance.

order ranks by amount in the category’s normal direction, so desc lists the vendors you spent the most with first under an expense category, and the customers who paid you the most first under an income category. limit returns the first rows in whichever order applies; page with next_cursor.

Merchant names are exact, so spelling variants are separate rows; activity without a name is one row with merchant: null. Signs, refreshed_at, and the rejected period and department_id parameters work as in GET /aggregations/total.

GET

aggregations

totals

List totals

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

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

fetch('https://app.finta.com/api/v1/aggregations/totals', 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/totals",
  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/totals"

	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/totals")

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": "list",
  "url": "/api/v1/aggregations/totals",
  "group_by": "merchant",
  "order": "desc",
  "category_id": "cat_o5p6q7r8s9t0u1",
  "merchant": null,
  "start_date": "2026-01-01",
  "end_date": "2026-09-30",
  "date": null,
  "point_in_time": false,
  "currency": "USD",
  "refreshed_at": 1786992120,
  "has_more": true,
  "next_cursor": "WyJtZXJjaGFudCIsImRlc2MiLDE4MjM0MCwiQVdTIl0",
  "data": [
    {
      "object": "merchant_total",
      "merchant": "Gusto",
      "total_cents": -4825000,
      "debit_cents": 4825000,
      "credit_cents": 0
    },
    {
      "object": "merchant_total",
      "merchant": "AWS",
      "total_cents": -182340,
      "debit_cents": 190340,
      "credit_cents": 8000
    }
  ]
}

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]+$

group_by

enum<string>

required

merchant to rank merchants, or month for one row per calendar month.

Available options:

merchant,

month

start_date

string<date>

First selected month, as YYYY-MM-DD. Required for a periodic category, and for any category with group_by=month. The day is ignored. The deprecated start_month and end_month of GET /aggregations/total are not supported here.

end_date

string<date>

Last selected month, included, as YYYY-MM-DD. Required for a periodic category, and for any category with group_by=month. The day is ignored.

date

string<date>

Selected month for a point-in-time category with group_by=merchant, as YYYY-MM-DD. Rejected for periodic categories and with group_by=month. The day is ignored.

merchant

string

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

order

enum<string>

desc lists the largest amounts first and asc the smallest first, measured in the category's normal direction (so desc is the biggest spend first under an expense category). Defaults to desc for merchants. Months without order are in calendar order. Ties are listed by merchant name, or by month oldest first. A merchant whose refunds exceeded its charges under an expense category comes last with desc.

Available options:

asc,

desc

limit

integer

Number of rows to return, from 1 to 500, taken from the start of whichever order applies. Defaults to 100 for merchants; months return every month unless it is given.

Required range: 1 <= x <= 500

starting_after

string

The next_cursor value from the previous response, unchanged. Use it with the same request parameters; a cursor from a different request is rejected. Pages are not a frozen snapshot, so rows can shift if data changes between requests.

Response

The category total, grouped

object

enum<string>

required

Available options:

list

url

enum<string>

required

Available options:

/api/v1/aggregations/totals

group_by

enum<string>

required

The requested grouping.

Available options:

merchant,

month

order

enum<string> | null

required

The order used. Null for months requested without order, which are in calendar order, oldest first.

Available options:

asc,

desc

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.

start_date

string<date> | null

required

The requested start date. Null for a point-in-time category with group_by=merchant.

end_date

string<date> | null

required

The requested end date. Null for a point-in-time category with group_by=merchant.

date

string<date> | null

required

The requested point-in-time date. Set only for a point-in-time category with group_by=merchant.

point_in_time

boolean

required

When true, each row is a balance through the end of its month (or through date) rather than activity over the period.

currency

enum<string>

required

ISO 4217 currency code for every amount in data.

Available options:

USD

refreshed_at

integer | null

required

Unix timestamp of the most recent change to data in the returned rows. Null when no data matches.

has_more

boolean

required

True when more rows follow. Always false for months requested without limit.

next_cursor

string | null

required

Pass as starting_after, with the same request parameters, for the next page. Null when has_more is false.

data

object[]

required

Option 1
Option 2

Show child attributes

List totals

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

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

fetch('https://app.finta.com/api/v1/aggregations/totals', 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/totals",
  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/totals"

	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/totals")

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": "list",
  "url": "/api/v1/aggregations/totals",
  "group_by": "merchant",
  "order": "desc",
  "category_id": "cat_o5p6q7r8s9t0u1",
  "merchant": null,
  "start_date": "2026-01-01",
  "end_date": "2026-09-30",
  "date": null,
  "point_in_time": false,
  "currency": "USD",
  "refreshed_at": 1786992120,
  "has_more": true,
  "next_cursor": "WyJtZXJjaGFudCIsImRlc2MiLDE4MjM0MCwiQVdTIl0",
  "data": [
    {
      "object": "merchant_total",
      "merchant": "Gusto",
      "total_cents": -4825000,
      "debit_cents": 4825000,
      "credit_cents": 0
    },
    {
      "object": "merchant_total",
      "merchant": "AWS",
      "total_cents": -182340,
      "debit_cents": 190340,
      "credit_cents": 8000
    }
  ]
}

API Reference

Company

Team

Categories

Rules

Departments

Integrations

Aggregations

Transactions

Journal Entries

Parties

Reports

List totals

Authorizations

Query Parameters

Response