Skip to main content
The Insights API provides analytical data about your financial transactions, broken down by various dimensions like accounts, categories, budgets, bills, and tags.

​
Overview

Insights are available for three transaction types:
  • Expenses (/api/v1/insight/expense/*)
  • Income (/api/v1/insight/income/*)
  • Transfers (/api/v1/insight/transfer/*)
Each insight endpoint returns summarized financial data grouped by a specific dimension (accounts, categories, etc.) for a given date range.
All insight endpoints require date range parameters (start and end) and return data grouped by the specified dimension with currency information.

​
Expense Insights

Analyze your spending patterns across different dimensions.

​
Base Path

/api/v1/insight/expense

​
Get Expenses by Expense Account

View expenses grouped by destination expense accounts. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/expense?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
​
start
date
required
Start date in YYYY-MM-DD format
​
end
date
required
End date in YYYY-MM-DD format
​
accounts
string
Comma-separated list of asset account IDs to filter
​
id
string
Expense account ID
​
name
string
Expense account name
​
difference
string
Total expense amount as string
​
difference_float
number
Total expense amount as float
​
currency_id
string
Currency ID
​
currency_code
string
Currency code (e.g., USD, EUR)

​
Get Expenses by Asset Account

View expenses grouped by source asset accounts (where money came from). 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/asset?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Total Expenses

Get total expenses for the period. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/total?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Expenses by Bill

View expenses grouped by associated bills. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/bill?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Expenses Without Bill

View expenses that are not associated with any bill. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/no-bill?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Expenses by Budget

View expenses grouped by budget. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/budget?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Expenses Without Budget

View expenses that are not assigned to any budget. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/no-budget?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Expenses by Category

View expenses grouped by category. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/category?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Expenses Without Category

View expenses that have no category assigned. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/no-category?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Expenses by Tag

View expenses grouped by tag. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/tag?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Expenses Without Tag

View expenses that have no tags. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/no-tag?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Income Insights

Analyze your income patterns across different dimensions.

​
Base Path

/api/v1/insight/income

​
Get Income by Revenue Account

View income grouped by source revenue accounts. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/income/revenue?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Income by Asset Account

View income grouped by destination asset accounts (where money went). 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/income/asset?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Total Income

Get total income for the period. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/income/total?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Income by Category

View income grouped by category. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/income/category?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Income Without Category

View income that has no category assigned. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/income/no-category?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Income by Tag

View income grouped by tag. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/income/tag?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Income Without Tag

View income that has no tags. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/income/no-tag?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Transfer Insights

Analyze transfers between your accounts.

​
Base Path

/api/v1/insight/transfer

​
Get Transfers by Asset Account

View transfers grouped by asset accounts. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/transfer/asset?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Transfers by Category

View transfers grouped by category. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/transfer/category?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Transfers Without Category

View transfers that have no category assigned. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/transfer/no-category?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Transfers by Tag

View transfers grouped by tag. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/transfer/tag?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Transfers Without Tag

View transfers that have no tags. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/transfer/no-tag?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Total Transfers

Get total transfers for the period. 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/transfer/total?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Common Parameters

All insight endpoints accept these parameters:
​
start
date
required
Start date for the analysis period (format: YYYY-MM-DD)
​
end
date
required
End date for the analysis period (format: YYYY-MM-DD)
​
accounts
string
Comma-separated list of account IDs to filter results. Only transactions involving these accounts will be included.

​
Response Format

All insight endpoints return an array of objects with this structure:
​
id
string
ID of the grouped entity (account, category, tag, etc.)
​
name
string
Name of the grouped entity
​
difference
string
Total amount as a string for precise decimal handling
​
difference_float
number
Total amount as a float for easier numerical operations
​
currency_id
string
ID of the currency
​
currency_code
string
ISO currency code (USD, EUR, GBP, etc.)
The difference field is returned as both a string and float. Use the string value for precise decimal arithmetic to avoid floating-point precision issues.

​
Use Cases

​
Monthly Expense Analysis

Analyze spending by category for a specific month: 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/category?start=2024-11-01&end=2024-11-30" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Budget vs Actual

Compare budgeted vs actual spending: 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/expense/budget?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Income Sources

Identify your income sources: 
curl -X GET "https://your-firefly-instance.com/api/v1/insight/income/revenue?start=2024-01-01&end=2024-12-31" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Future Enhancements

The following features are planned for future versions:
  • Insights by object group
  • Insights by recurrence
  • Currency-specific filtering
  • Net worth tracking via insights
Insight data is calculated in real-time and may take longer for large date ranges or accounts with many transactions.

​
Next Steps

Charts API

Get chart-ready data for visualization

Search API

Search and filter transactions