> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Bulk Wallet Balances

> Return cash balances across up to 100 connected users in one call, one result per target.

Returns cash balances across up to **100 connected users** in one call, one result per target.

## Requirements

* `Authorization: Basic <API_KEY>` (your application API key)
* The **bulk API capability** on your application
* The `LIST_PAYMENT` scope on each target user's grant

Failures are reported per target and never fail the whole request. See [Bulk API Overview](/bulk-api) for the targeting model and error codes.

## Query

```graphql theme={null}
query GetBulkBalances($targetSpec: BulkTargetSpecInput!) {
  getBulkBalances(targetSpec: $targetSpec) {
    targetCount
    successCount
    failureCount
    results {
      externalReferenceId
      accountId
      success
      error { code message }
      balances {
        userCashBalanceId
        nickname
        status
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        createdAt
      }
    }
  }
}
```

### Variables — selected users

```json theme={null}
{
  "targetSpec": { "mode": "SELECTED", "targets": ["your-user-001", "your-user-002"] }
}
```

### Variables — all connected users

```json theme={null}
{
  "targetSpec": { "mode": "ALL_CONNECTED" }
}
```

## Response

```json theme={null}
{
  "data": {
    "getBulkBalances": {
      "targetCount": 2,
      "successCount": 1,
      "failureCount": 1,
      "results": [
        {
          "externalReferenceId": "your-user-001",
          "accountId": "8f3c…",
          "success": true,
          "error": null,
          "balances": [
            {
              "userCashBalanceId": "ucb-1",
              "nickname": "Main account",
              "status": "ACTIVE",
              "totalCashBalance": "125.50",
              "availableCashBalance": "100.00",
              "lifetimeCashBalance": "500.00",
              "createdAt": "2026-01-01T00:00:00.000Z"
            }
          ]
        },
        {
          "externalReferenceId": "your-user-002",
          "accountId": "a90d…",
          "success": false,
          "error": {
            "code": "INSUFFICIENT_SCOPE",
            "message": "The user has not granted the scopes this operation requires. Missing scopes: LIST_PAYMENT."
          },
          "balances": null
        }
      ]
    }
  }
}
```

## Arguments

| Argument             | Type              | Description                                                                                                                                          |
| -------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `targetSpec.mode`    | `BulkTargetMode!` | `ALL_CONNECTED` or `SELECTED`.                                                                                                                       |
| `targetSpec.targets` | `[String!]`       | `externalReferenceId`s to target. Required for `SELECTED`; ignored for `ALL_CONNECTED`. Duplicates removed; result order follows this list. Max 100. |

## Response fields

| Field                                           | Description                                                                                              |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `results[].success`                             | Whether balances were returned for this target.                                                          |
| `results[].error`                               | Present when `success` is `false`. See error codes in the [Overview](/bulk-api).                         |
| `results[].balances`                            | The user's cash balances. Restricted to permitted spend accounts when the grant is spend-account-scoped. |
| `targetCount` / `successCount` / `failureCount` | Request-level summary.                                                                                   |

<Note>
  A target whose grant is scoped to specific spend accounts returns only those balances — automatically, with no extra parameters.
</Note>