Get User Spending Analysis V2 Endpoint

curl --request GET \
  --url https://api.mytruv.com/v2/users/spending \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.mytruv.com/v2/users/spending"

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

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

fetch('https://api.mytruv.com/v2/users/spending', 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://api.mytruv.com/v2/users/spending",
  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://api.mytruv.com/v2/users/spending"

	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))

}

HttpResponse<String> response = Unirest.get("https://api.mytruv.com/v2/users/spending")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mytruv.com/v2/users/spending")

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

{
  "spending": {
    "by_category": [
      {
        "category": "<string>",
        "total_amount": "<string>",
        "transaction_count": 123,
        "average_transaction": "<string>",
        "percentage_of_total": "<string>",
        "largest_transaction": {
          "transaction_id": "<string>",
          "amount": "<string>",
          "date": "2023-12-25",
          "description": "<string>",
          "merchant_category_code": "5812"
        },
        "subcategories": [
          {
            "name": "<string>",
            "amount": "<string>",
            "count": 123
          }
        ],
        "time_series": [
          {
            "end_date": "<string>",
            "amount": "<string>",
            "count": 123,
            "start_date": "2025-10-16"
          }
        ],
        "trend": "5.0"
      }
    ],
    "by_merchant": [
      {
        "merchant_name": "<string>",
        "category": "<string>",
        "total_amount": "<string>",
        "transaction_count": 123,
        "average_transaction": "<string>",
        "percentage_of_total": "<string>",
        "is_recurring": true,
        "largest_transaction": {
          "transaction_id": "<string>",
          "amount": "<string>",
          "date": "2023-12-25",
          "description": "<string>",
          "merchant_category_code": "5812"
        },
        "time_series": [
          {
            "end_date": "<string>",
            "amount": "<string>",
            "count": 123,
            "start_date": "2025-10-16"
          }
        ],
        "trend": "5.0"
      }
    ],
    "by_time_period": [
      {
        "end_date": "<string>",
        "total_amount": "<string>",
        "transaction_count": 123,
        "average_transaction": "<string>",
        "percentage_of_total": "<string>",
        "largest_transaction": {
          "transaction_id": "<string>",
          "amount": "<string>",
          "date": "2023-12-25",
          "description": "<string>",
          "merchant_category_code": "5812"
        },
        "start_date": "2025-10-02",
        "trend": "5.0"
      }
    ]
  },
  "summary": {
    "total_spending": "<string>",
    "average_daily_spending": "<string>",
    "average_monthly_spending": "<string>",
    "total_transactions": 123,
    "unique_merchants": 123,
    "top_category": "<string>",
    "top_merchant": "<string>"
  },
  "request_id": "<string>",
  "created_at": "<string>",
  "by_time_period": [
    {
      "end_date": "<string>",
      "total_amount": "<string>",
      "transaction_count": 123,
      "percentage_of_total": "<string>",
      "breakdown": [
        {
          "name": "<string>",
          "amount": "<string>",
          "transaction_count": 123,
          "percentage": "<string>"
        }
      ],
      "start_date": "2024-01-01",
      "trend": "5.5"
    }
  ],
  "total_income": "4345.00",
  "total_expenses": "10550.00",
  "savings_rate": "-142.8"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Spending

Get Spending Analysis

Get spending analysis for the authenticated user (v2, ClickHouse-backed).

Returns categorized spending breakdown with totals. Returns empty lists when no transactions match. Reads from ClickHouse instead of Core API for improved performance and correctness.

Double aggregation: Use group_by=time_period with secondary_group_by=category or secondary_group_by=merchant to get a breakdown within each time period (top 10 + “Other”).

The end_date is capped at today if it is in the future or omitted.

Note: Transactions from INVESTMENT-type accounts (brokerage, crypto, IRA, etc.) are always excluded — stock purchases, short sales, dividend reinvestments, and margin interest are not personal spending. Passing an investment account_id in account_ids will therefore return empty results for that account.

DEBIT transfers to investment platforms (Wealthfront, Robinhood, Fidelity, Schwab, Vanguard, Coinbase, etc.) are also excluded even when the investment account itself is not connected. The matching uses merchant name and description patterns, guarded against known false positives (e.g. “Les Schwab Tires”, “Fidelity Life Insurance”). CREDITs from these platforms (withdrawals, dividends) are kept — they are real cashflow into the user’s spending accounts.

GET

users

spending

Get User Spending Analysis V2 Endpoint

curl --request GET \
  --url https://api.mytruv.com/v2/users/spending \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.mytruv.com/v2/users/spending"

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

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

fetch('https://api.mytruv.com/v2/users/spending', 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://api.mytruv.com/v2/users/spending",
  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://api.mytruv.com/v2/users/spending"

	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))

}

HttpResponse<String> response = Unirest.get("https://api.mytruv.com/v2/users/spending")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mytruv.com/v2/users/spending")

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

{
  "spending": {
    "by_category": [
      {
        "category": "<string>",
        "total_amount": "<string>",
        "transaction_count": 123,
        "average_transaction": "<string>",
        "percentage_of_total": "<string>",
        "largest_transaction": {
          "transaction_id": "<string>",
          "amount": "<string>",
          "date": "2023-12-25",
          "description": "<string>",
          "merchant_category_code": "5812"
        },
        "subcategories": [
          {
            "name": "<string>",
            "amount": "<string>",
            "count": 123
          }
        ],
        "time_series": [
          {
            "end_date": "<string>",
            "amount": "<string>",
            "count": 123,
            "start_date": "2025-10-16"
          }
        ],
        "trend": "5.0"
      }
    ],
    "by_merchant": [
      {
        "merchant_name": "<string>",
        "category": "<string>",
        "total_amount": "<string>",
        "transaction_count": 123,
        "average_transaction": "<string>",
        "percentage_of_total": "<string>",
        "is_recurring": true,
        "largest_transaction": {
          "transaction_id": "<string>",
          "amount": "<string>",
          "date": "2023-12-25",
          "description": "<string>",
          "merchant_category_code": "5812"
        },
        "time_series": [
          {
            "end_date": "<string>",
            "amount": "<string>",
            "count": 123,
            "start_date": "2025-10-16"
          }
        ],
        "trend": "5.0"
      }
    ],
    "by_time_period": [
      {
        "end_date": "<string>",
        "total_amount": "<string>",
        "transaction_count": 123,
        "average_transaction": "<string>",
        "percentage_of_total": "<string>",
        "largest_transaction": {
          "transaction_id": "<string>",
          "amount": "<string>",
          "date": "2023-12-25",
          "description": "<string>",
          "merchant_category_code": "5812"
        },
        "start_date": "2025-10-02",
        "trend": "5.0"
      }
    ]
  },
  "summary": {
    "total_spending": "<string>",
    "average_daily_spending": "<string>",
    "average_monthly_spending": "<string>",
    "total_transactions": 123,
    "unique_merchants": 123,
    "top_category": "<string>",
    "top_merchant": "<string>"
  },
  "request_id": "<string>",
  "created_at": "<string>",
  "by_time_period": [
    {
      "end_date": "<string>",
      "total_amount": "<string>",
      "transaction_count": 123,
      "percentage_of_total": "<string>",
      "breakdown": [
        {
          "name": "<string>",
          "amount": "<string>",
          "transaction_count": 123,
          "percentage": "<string>"
        }
      ],
      "start_date": "2024-01-01",
      "trend": "5.5"
    }
  ],
  "total_income": "4345.00",
  "total_expenses": "10550.00",
  "savings_rate": "-142.8"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication with a personal access token (prefix pat_). Generate tokens in the Truv web app under Settings → API keys.

Query Parameters

group_by

enum<string>

required

Available options:

category,

merchant,

time_period

time_period

enum<string>

required

Available options:

day,

week,

month,

quarter,

year

link_id

string | null

start_date

string<date> | null

end_date

string<date> | null

account_ids

string | null

Response

Spending analysis with optional double aggregation (v2).

Spending analysis response with optional double aggregation.

Wraps the Truv API response and adds by_time_period with breakdown when secondary_group_by is specified.

spending

SpendingData · object

required

Spending data from Truv API.

Show child attributes

summary

SpendingSummary · object

required

Summary statistics from Truv API.

Show child attributes

request_id

string

required

Unique request identifier.

created_at

string

required

Analysis creation timestamp.

by_time_period

TimePeriodSpendingEnriched · object[] | null

Time periods with category/merchant breakdown. Only present when group_by=time_period and secondary_group_by is set.

Show child attributes

total_income

string | null

Whole-window CREDIT total on the same hide-aware basis as the spending side (same hide, internal-transfer, and investment exclusions; scoped by link_id and account_ids). It is a whole-window figure and is NOT narrowed by the categories breakdown filter or the include_income flag. Null on the legacy v1 endpoint, which does not compute cash flow.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"4345.00"

total_expenses

string | null

Whole-window DEBIT total on the same basis as total_income. Pairs with total_income to derive the savings rate. Unlike summary.total_spending it is never signed against income and is not narrowed by the categories filter, so use this (not summary.total_spending) when displaying the savings rate. Null on the legacy v1 endpoint.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"10550.00"

savings_rate

string | null

(total_income minus total_expenses) as a percentage of total_income, one decimal place. Can be negative when expenses exceed income. Null when total_income is zero or negative (undefined) or on the legacy v1 endpoint.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"-142.8"

The Spending Analysis object

The Income object

⌘I