The Spending Analysis object

The Spending Analysis response provides spending data grouped by category, merchant, or time period, along with summary statistics.

Summary attributes

Attribute	Type	Description
total_spending	string	Total spending amount
average_daily_spending	string	Average daily spending
average_monthly_spending	string	Average monthly spending
total_transactions	integer	Total number of transactions
unique_merchants	integer	Number of unique merchants
top_category	string	Highest-spending category
top_merchant	string	Highest-spending merchant

Spending data attributes

Attribute	Type	Description
by_category	array of objects	Spending grouped by category
by_merchant	array of objects	Spending grouped by merchant
by_time_period	array of objects	Spending grouped by time period. See Time period attributes

Time period attributes

Each entry in spending.by_time_period. This is a different object from the top-level by_time_period described below, which carries a category or merchant breakdown instead.

Attribute	Type	Description
time_period	string	Bucket size: `day`, `week`, `month`, `quarter`, or `year`
start_date	string	Bucket start date (YYYY-MM-DD). May be null
end_date	string	Bucket end date (YYYY-MM-DD)
total_amount	string	Total spending in this bucket
transaction_count	integer	Number of transactions counted in this bucket
average_transaction	string	Average transaction amount
percentage_of_total	string	Percentage of grand total spending
trend	string	Percentage change from the previous bucket. May be null
largest_transaction	object	Largest single transaction in this bucket, with `transaction_id`, `amount`, `date`, `description`, and `merchant_category_code`
transaction_ids	array of strings	IDs of the transactions counted in this bucket. Null except on a single-day request. See Transaction IDs

Transaction IDs

transaction_ids lets you show exactly which transactions make up a day’s total. It is populated only when you request a single day, that is group_by=time_period&time_period=day with start_date equal to end_date. On every other grouping it is null. The values are transaction_id, the same id the transactions endpoint returns, not external_id. When present, the list is exactly the set of transactions behind transaction_count, so the two always agree in length. Internal transfers, investment account activity, and transfers to investment platforms are already excluded. Match on these IDs rather than applying those exclusion rules yourself.

Response attributes

Attribute	Type	Description
spending	object	Spending data from MyTruv API
summary	object	Summary statistics
request_id	string	Unique request identifier
created_at	string	Analysis creation timestamp
by_time_period	array of objects	Time periods with category/merchant breakdown (only when `group_by=time_period` and `secondary_group_by` is set)
total_income	string	Total income (credits) across the period. Null unless `include_income=true`.
total_expenses	string	Total expenses (debits) across the period.
savings_rate	string	Share of income retained, as a percentage. Null unless income is included.

Endpoints

Get spending analysis

Example response

{
  "spending": {
    "by_category": [
      {
        "category": "Food & Dining",
        "total_amount": "1250.00",
        "transaction_count": 45,
        "average_transaction": "27.78",
        "percentage_of_total": "24.5"
      }
    ],
    "by_merchant": [
      {
        "merchant_name": "Whole Foods",
        "total_amount": "850.00",
        "transaction_count": 12,
        "average_transaction": "70.83",
        "percentage_of_total": "16.7"
      }
    ]
  },
  "summary": {
    "total_spending": "5100.00",
    "average_daily_spending": "170.00",
    "average_monthly_spending": "5100.00",
    "total_transactions": 249,
    "unique_merchants": 3,
    "top_category": "Food & Dining",
    "top_merchant": "Whole Foods"
  },
  "request_id": "req_abc123",
  "created_at": "2025-03-15T10:00:00Z",
  "total_income": null,
  "total_expenses": "5100.00",
  "savings_rate": null
}

Single day, with transaction IDs

A request for one day (group_by=time_period&time_period=day&start_date=2026-05-01&end_date=2026-05-01) returns the bucket with transaction_ids filled in.

{
  "spending": {
    "by_time_period": [
      {
        "time_period": "day",
        "start_date": "2026-05-01",
        "end_date": "2026-05-01",
        "total_amount": "112.40",
        "transaction_count": 2,
        "average_transaction": "56.20",
        "percentage_of_total": "100.0",
        "trend": null,
        "largest_transaction": {
          "transaction_id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "amount": "78.90",
          "date": "2026-05-01",
          "description": "Whole Foods Market",
          "merchant_category_code": "5411"
        },
        "transaction_ids": [
          "24d7e80942ce4ad58a93f70ce4115f5c",
          "5dfb80aaaae14ef8938f355ba1d0cadf"
        ]
      }
    ]
  },
  "summary": {
    "total_spending": "112.40",
    "average_daily_spending": "112.40",
    "average_monthly_spending": "112.40",
    "total_transactions": 2,
    "unique_merchants": 2,
    "top_category": "Groceries",
    "top_merchant": "Whole Foods Market"
  },
  "request_id": "req_def456",
  "created_at": "2026-05-02T08:00:00Z",
  "total_income": null,
  "total_expenses": "112.40",
  "savings_rate": null
}

Overview

User

Balances

Transactions

Spending

Income

Recurring Transactions

Balance History

Liabilities

Credit

Account Links

The Spending Analysis object

Summary attributes

Spending data attributes

Time period attributes

Transaction IDs

Response attributes

Endpoints

Example response

Single day, with transaction IDs

​Summary attributes

​Spending data attributes

​Time period attributes

​Transaction IDs

​Response attributes

​Endpoints

​Example response

​Single day, with transaction IDs

Summary attributes

Spending data attributes

Time period attributes

Transaction IDs

Response attributes

Endpoints

Example response

Single day, with transaction IDs