Get Balances

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

Returns live balances for the specified accounts. Balances are fetched directly from the banking provider on each request. No balance data is stored on Redbark servers.

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

Balances may be served from a short-lived server-side cache for up to 30 minutes; see Caching for purge and opt-out behaviour. Returned in the order the provider responds (iterates by provider, then by each provider’s response ordering, so accounts on different providers are interleaved per-provider); not guaranteed to match the input order.

{
  "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)
`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.

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
`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`	(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

MCP Server

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