Get budget status
curl --request GET \
--url https://api.finta.io/v2/budgets/status \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.finta.io/v2/budgets/status"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.finta.io/v2/budgets/status', 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.finta.io/v2/budgets/status",
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.finta.io/v2/budgets/status"
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.finta.io/v2/budgets/status")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.finta.io/v2/budgets/status")
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{
"planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"method": "standard",
"accountScope": "All",
"isDefault": true
},
"period": {
"key": "2026-11",
"cadence": "monthly",
"startDate": "2023-12-25",
"endDate": "2023-12-25"
},
"currency": "<string>",
"totals": {
"planned": 123,
"spent": 123,
"rollover": 123,
"available": 123,
"unbudgetedSpent": 123,
"uncategorizedSpent": 123,
"totalSpent": 123
},
"readyToAssign": 123,
"readyToAssignBreakdown": {
"cashBalance": 123,
"stillAvailableInBudgets": 123,
"setAsideForCardPayments": 123,
"assignedToFutureMonths": 123,
"cashSpentOutsideBudgets": 123
},
"assignedInFuture": 123,
"spentOutsideEnvelopes": 123,
"balancesAsOf": "2023-11-07T05:31:56Z",
"budgets": [
{
"budgetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"targetType": "category",
"categoryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"categoryGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"categoryIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"rolloverEnabled": true,
"planned": 123,
"plannedSource": "template",
"suggestedAmount": 123,
"overrideSource": "user_edited",
"spent": 123,
"rollover": 123,
"available": 123,
"isOverBudget": true,
"pace": {
"periodElapsedRatio": 123,
"spentRatio": 123,
"status": "under",
"projectedSpend": 123
},
"targetProgress": {
"targetAmount": 123,
"targetDate": "2023-12-25",
"currentAmount": 123,
"remainingAmount": 123,
"progressRatio": 123,
"isMet": true,
"periodsRemaining": 123,
"requiredPerPeriod": 123
},
"rolloverPeriodsWalked": 123
}
],
"unbudgeted": [
{
"categoryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"categoryGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"spent": 123
}
],
"paymentEnvelopes": [
{
"budgetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"assigned": 123,
"rollover": 123,
"movedIn": 123,
"paid": 123,
"available": 123,
"overpaid": 123,
"owed": 123,
"uncoveredLastMonth": 123,
"institutionAccountName": "<string>"
}
],
"unrecognizedCardInflows": {
"count": 123,
"amount": 123,
"accountIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
},
"meta": {
"planCount": 123,
"budgetCount": 123,
"rolloverBudgetCount": 123,
"maxRolloverPeriodsWalked": 123,
"totalRolloverPeriodsWalked": 123,
"rolloverWalkTruncated": true,
"queryCount": 123
},
"includesAccountsOutsideConsent": true,
"accountsOutsideConsent": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
}
],
"freshness": {
"asOf": "2023-11-07T05:31:56Z",
"connections": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"status": "ok",
"lastSuccessAt": "2023-11-07T05:31:56Z",
"errorMessage": "<string>",
"reconnectUrl": "<string>"
}
]
}
}{
"error": {
"code": "STORAGE_MODE_REQUIRED",
"message": "<string>"
}
}{
"error": "Missing or invalid Authorization header"
}{
"error": {
"code": "STORAGE_MODE_REQUIRED",
"message": "<string>"
}
}{
"error": {
"code": "STORAGE_MODE_REQUIRED",
"message": "<string>"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Per-minute rate limit exceeded (standard plan)"
}
}Budgets
Get budget status
Returns planned, spent, rollover, available and pace for each budget in one plan and month, plus totals and spending no budget covers. Envelope plans also return readyToAssign, readyToAssignBreakdown, paymentEnvelopes and unrecognizedCardInflows. Finta computes every number at request time and counts only the plan’s accounts. When includesAccountsOutsideConsent is true, the totals include accounts this key was not granted, named in accountsOutsideConsent, and their transactions stay unavailable to it. plan is null if the user has no budgets yet.
GET
/
budgets
/
status
Get budget status
curl --request GET \
--url https://api.finta.io/v2/budgets/status \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.finta.io/v2/budgets/status"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.finta.io/v2/budgets/status', 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.finta.io/v2/budgets/status",
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.finta.io/v2/budgets/status"
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.finta.io/v2/budgets/status")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.finta.io/v2/budgets/status")
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{
"planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"plan": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"method": "standard",
"accountScope": "All",
"isDefault": true
},
"period": {
"key": "2026-11",
"cadence": "monthly",
"startDate": "2023-12-25",
"endDate": "2023-12-25"
},
"currency": "<string>",
"totals": {
"planned": 123,
"spent": 123,
"rollover": 123,
"available": 123,
"unbudgetedSpent": 123,
"uncategorizedSpent": 123,
"totalSpent": 123
},
"readyToAssign": 123,
"readyToAssignBreakdown": {
"cashBalance": 123,
"stillAvailableInBudgets": 123,
"setAsideForCardPayments": 123,
"assignedToFutureMonths": 123,
"cashSpentOutsideBudgets": 123
},
"assignedInFuture": 123,
"spentOutsideEnvelopes": 123,
"balancesAsOf": "2023-11-07T05:31:56Z",
"budgets": [
{
"budgetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"targetType": "category",
"categoryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"categoryGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"categoryIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"rolloverEnabled": true,
"planned": 123,
"plannedSource": "template",
"suggestedAmount": 123,
"overrideSource": "user_edited",
"spent": 123,
"rollover": 123,
"available": 123,
"isOverBudget": true,
"pace": {
"periodElapsedRatio": 123,
"spentRatio": 123,
"status": "under",
"projectedSpend": 123
},
"targetProgress": {
"targetAmount": 123,
"targetDate": "2023-12-25",
"currentAmount": 123,
"remainingAmount": 123,
"progressRatio": 123,
"isMet": true,
"periodsRemaining": 123,
"requiredPerPeriod": 123
},
"rolloverPeriodsWalked": 123
}
],
"unbudgeted": [
{
"categoryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"categoryGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"spent": 123
}
],
"paymentEnvelopes": [
{
"budgetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"assigned": 123,
"rollover": 123,
"movedIn": 123,
"paid": 123,
"available": 123,
"overpaid": 123,
"owed": 123,
"uncoveredLastMonth": 123,
"institutionAccountName": "<string>"
}
],
"unrecognizedCardInflows": {
"count": 123,
"amount": 123,
"accountIds": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
},
"meta": {
"planCount": 123,
"budgetCount": 123,
"rolloverBudgetCount": 123,
"maxRolloverPeriodsWalked": 123,
"totalRolloverPeriodsWalked": 123,
"rolloverWalkTruncated": true,
"queryCount": 123
},
"includesAccountsOutsideConsent": true,
"accountsOutsideConsent": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>"
}
],
"freshness": {
"asOf": "2023-11-07T05:31:56Z",
"connections": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"status": "ok",
"lastSuccessAt": "2023-11-07T05:31:56Z",
"errorMessage": "<string>",
"reconnectUrl": "<string>"
}
]
}
}{
"error": {
"code": "STORAGE_MODE_REQUIRED",
"message": "<string>"
}
}{
"error": "Missing or invalid Authorization header"
}{
"error": {
"code": "STORAGE_MODE_REQUIRED",
"message": "<string>"
}
}{
"error": {
"code": "STORAGE_MODE_REQUIRED",
"message": "<string>"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Per-minute rate limit exceeded (standard plan)"
}
}Authorizations
Query Parameters
Response
Budget status for the month