> ## 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.

# Obtener saldos masivos

> Devuelve saldos en efectivo de hasta 100 usuarios conectados en una sola llamada, un resultado por objetivo.

Devuelve saldos en efectivo de hasta **100 usuarios conectados** en una sola llamada, un resultado por objetivo.

## Requisitos

* `Authorization: Basic <API_KEY>` (la clave API de tu aplicación)
* La **capacidad de API masiva** en tu aplicación
* El alcance `LIST_PAYMENT` en la concesión de cada usuario objetivo

Las fallas se informan por objetivo y nunca hacen fallar toda la solicitud. Consulta [Descripción general de la API masiva](/bulk-api) para el modelo de segmentación y los códigos de error.

## Consulta

```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 — usuarios seleccionados

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

### Variables — todos los usuarios conectados

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

## Respuesta

```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
        }
      ]
    }
  }
}
```

## Argumentos

| Argumento            | Tipo              | Descripción                                                                                                                                                           |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `targetSpec.mode`    | `BulkTargetMode!` | `ALL_CONNECTED` o `SELECTED`.                                                                                                                                         |
| `targetSpec.targets` | `[String!]`       | `externalReferenceId`s a los que apuntar. Requerido para `SELECTED`; se ignora para `ALL_CONNECTED`. Los duplicados se eliminan; el orden sigue esta lista. Máx. 100. |

## Campos de la respuesta

| Campo                                           | Descripción                                                                                                                             |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `results[].success`                             | Indica si se devolvieron saldos para este objetivo.                                                                                     |
| `results[].error`                               | Presente cuando `success` es `false`. Consulta los códigos de error en la [Descripción general](/bulk-api).                             |
| `results[].balances`                            | Los saldos en efectivo del usuario. Restringido a las cuentas de gasto permitidas cuando la concesión está limitada a cuentas de gasto. |
| `targetCount` / `successCount` / `failureCount` | Resumen a nivel de solicitud.                                                                                                           |

<Note>
  Un objetivo cuya concesión está limitada a cuentas de gasto específicas devuelve solo esos saldos — automáticamente, sin parámetros adicionales.
</Note>