Get Balances

Retrieve live account balances for one or more accounts

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 if their trial plan is Professional).

Response headers

Header	Description
X-Cache	HIT, MISS, or BYPASS. Set unconditionally by the cache layer; useful for debugging stale data and tuning poll frequency.

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 — filter by category from /v1/accounts and route brokerage IDs to /v1/holdings.

Response

Cached at the edge for 5 minutes. Cache key is userId + path + sorted query string, so different orderings or duplicates of accountIds produce different cache entries. Responses containing any null balance are not cached — the next request will re-fetch from the provider, so a transient blip on one account in a multi-account request will not pin the failure for the full TTL. Returned in the order the provider responds (iterates by provider, then by each provider’s response ordering — 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"). null if the provider call failed.

Balance values are strings to preserve decimal precision. Parse them as decimals in your application. All three balance fields are nullable — when the provider errors for a given account, that account comes back with currentBalance, availableBalance, and currency all null. Parsers must handle that case.

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	No accountIds provided
400	too_many_accounts	More than 100 accounts requested (checked after deduplication)
400	wrong_endpoint_for_category	Any requested account ID belongs to a brokerage connection. Message: Balances are only available for banking accounts — use /v1/holdings for brokerage accounts (...)
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.co/v1/balances?accountIds=acc_abc123,acc_def456"

Python

import requests

API_KEY = "YOUR_API_KEY"

# Get account IDs first
accounts_resp = requests.get(
    "https://api.redbark.co/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.co/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.co";

// 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})`);
}