Get Balances

v1 is deprecated. It stays available for existing integrations, with additive Fiskil balance freshness metadata. It will be sunset no earlier than 12 months after v2 reaches general availability (announced with Deprecation / Sunset headers). Build new work on API v2; see migrating from v1.

The REST API is in beta. This endpoint’s response shape may change.

Returns balances for the specified accounts. Fiskil balances are fresh for 4 hours; during transient failures or cooldowns, the last successful live observation may be served for up to 24 hours. Plaid balances are not cached; they reflect Plaid’s last successful update of the connection, typically about daily. Balance data is never written to Redbark’s primary database or logs.

Request

GET /v1/balances

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`

Trialing customers retain full API access, including brokerage endpoints, regardless of trial plan.

Query parameters

Parameter	Type	Required	Description
`accountIds`	`string`	Yes	Comma-separated list of account UUIDs. The list is deduplicated server-side, and the 100-account cap is checked after deduplication.

Use the List Accounts endpoint to get account IDs. Mixing a brokerage accountId into the request fails the entire request, not per-account. To tell banking and brokerage accounts apart, join each account’s connectionId to List Connections and check the connection’s category; route brokerage IDs to /v1/holdings.

Response

See Caching for provider-specific freshness, fallback, purge, and opt-out behaviour. Fiskil’s additive freshness fields prevent cached balances from being mistaken for new live observations. Results are not guaranteed to match the input order; join by accountId.

{
  "data": [
    {
      "accountId": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
      "currentBalance": "1234.56",
      "availableBalance": "1200.00",
      "currency": "AUD"
    },
    {
      "accountId": "b2c3d4e5-f6a7-8901-b2c3-d4e5f6a78901",
      "currentBalance": "8750.00",
      "availableBalance": "8750.00",
      "currency": "AUD"
    }
  ]
}

Balance object

Field	Type	Description
`accountId`	`string`	UUID of the account (matches IDs from the accounts endpoint)
`observedAt`	`string \| null`	Fiskil only: ISO timestamp of the successful live observation, unchanged on cache hits or stale fallback. Null when unavailable.
`freshness`	`string`	Fiskil only: `fresh` (under 4 hours), `stale` (transient-error fallback under 24 hours), or `unavailable`.
`currentBalance`	`string \| null`	Current balance as a decimal string. Negative if the account is in debit. `null` if the provider call failed for this account.
`availableBalance`	`string \| null`	Available balance (funds available for transfer). `null` if the provider call failed.
`currency`	`string \| null`	ISO 4217 currency code (e.g. `"AUD"`, `"NZD"`). Falls back to the account’s stored currency when the provider omits it, so it is usually present even when the balance fields are `null`. `null` only when no stored currency is available either.

When Redbark caching is disabled, Fiskil live balance attempts are limited to once per account every 15 minutes. An account inside that limit comes back in the list with freshness: "unavailable", null balances and retryAfterSec, the seconds until a live read is allowed again. The same applies when the account was not reached before the request ran out of time, or its connection is in a cooldown, deferred or temporarily unreachable. A call that runs out of time returns the accounts it did not reach this way, so merge results across calls. The other accounts in the call are returned normally. This endpoint never returns balance_refresh_limited.

Balance values are strings to preserve decimal precision. Parse them as decimals in your application. When the provider errors for a given account, currentBalance and availableBalance come back null; currency still resolves to the account’s stored currency where we have one. Parsers must handle null balances.

Error responses

Errors use the standard envelope { "error": { "message": string, "code"?: string, "details"?: string[] } }. The optional code field is set for the structured cases below — clients should branch on code rather than parsing message.

Status	`code`	When
`400`	`invalid_params`	`accountIds` is present but empty after trimming (e.g. `accountIds=,,`). A missing or empty `accountIds` param instead fails schema validation and returns `Invalid request parameters` with no `code`.
`400`	`too_many_accounts`	More than 100 accounts requested (checked after deduplication)
`400`	`wrong_endpoint_for_category`	A requested account belongs to a non-banking connection. Brokerage message: `Balances are only available for banking accounts. Use /v1/holdings for brokerage accounts (<ids>).` Documents message: `Balances are not available for these accounts (<ids>). Documents connections expose transactions only, via /v1/transactions.`
`404`	(none)	One or more accounts not found, or do not belong to you
`429` or `503`	`provider_wait`	Shared banking admission deferred the request; 429 is a per-account cooldown, 503 is pool capacity. Retry after `Retry-After`.
`429`	`upstream_rate_limited`	The banking provider itself rate-limited the request. Retry after `Retry-After`.
`501`	(none)	`Balances are not yet available for provider: <name>` — returned when an account belongs to a provider whose `getBalances` is not yet implemented
`503`	`gateway_unavailable`	The connection gateway could not be reached. Retry after `Retry-After`.
`503`	`upstream_timeout`	The read did not complete inside its request budget. Retry after `Retry-After`.
`503`	(none)	Banking provider temporarily unavailable. Retry later.

Example error body:

{
  "error": {
    "message": "Balances are only available for banking accounts. Use /v1/holdings for brokerage accounts (d4e5f6a7-b8c9-0123-d4e5-f6a7b8c90123).",
    "code": "wrong_endpoint_for_category"
  }
}

Examples

Basic request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.redbark.com/v1/balances?accountIds=a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890,b2c3d4e5-f6a7-8901-b2c3-d4e5f6a78901"

Python

import requests

API_KEY = "YOUR_API_KEY"

# Get account IDs first
accounts_resp = requests.get(
    "https://api.redbark.com/v1/accounts",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
account_ids = [a["id"] for a in accounts_resp.json()["data"]]

# Fetch balances for all accounts
resp = requests.get(
    "https://api.redbark.com/v1/balances",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"accountIds": ",".join(account_ids)},
)
balances = resp.json()["data"]

for b in balances:
    print(f"{b['accountId']}: {b['currency']} {b['currentBalance']} (available: {b['availableBalance']})")

JavaScript

const API_KEY = "YOUR_API_KEY";
const BASE = "https://api.redbark.com";

// Get account IDs first
const accountsResp = await fetch(`${BASE}/v1/accounts`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const { data: accounts } = await accountsResp.json();
const accountIds = accounts.map((a) => a.id).join(",");

// Fetch balances
const resp = await fetch(`${BASE}/v1/balances?accountIds=${accountIds}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const { data: balances } = await resp.json();

for (const b of balances) {
  console.log(`${b.accountId}: ${b.currency} ${b.currentBalance} (available: ${b.availableBalance})`);
}

Overview

Endpoints

CLI

SimpleFIN

Webhooks

Request

Headers

Query parameters

Response

Balance object

Error responses

Examples

Basic request

Python

JavaScript

​Request

​Headers

​Query parameters

​Response

​Balance object

​Error responses

​Examples

​Basic request

​Python

​JavaScript

Request

Headers

Query parameters

Response

Balance object

Error responses

Examples

Basic request

Python

JavaScript