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

# List user velocity control balances

> Retrieves a list of the available balances of the velocity controls associated with a user.

GET/velocitycontrols/user/\{user\_token}/available

Retrieves a list of the available balances of the velocity controls associated with a user. This operation is unavailable for velocity controls with a window of `TRANSACTION`, because available balances do not apply to single-transaction velocity windows.

Depending on the control, the balance can include an available monetary amount, the number of transactions remaining, and the number of days remaining in the time window.

This endpoint supports [field filtering](https://www.marqeta.com/docs/core-api/field-filtering.md) and [pagination](https://www.marqeta.com/docs/core-api/sorting-and-pagination.md).

## URL path parameters

| Fields | Description |
| - | - |
| user\_token string  Required | Unique identifier of the cardholder. **Allowable Values:**  Existing user token |

## URL query parameters

| Fields | Description |
| - | - |
| count integer  Optional | Number of available balance resources to retrieve. **Allowable Values:**  1-10 **Default value:** 5 |
| start\_index integer  Optional | The sort order index of the first resource in the returned array. **Allowable Values:**  Any integer **Default value:** 0 |
| fields string  Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. **Allowable Values:**  Comma-delimited list of fields, or blank |
| sort\_by string  Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. **Allowable Values:**  `createdTime`, `lastModifiedTime`, or any field in the resource model |

## Response body

| Fields | Description |
| - | - |
| count integer  Conditionally returned | Number of velocity control resources retrieved. This field is returned if there are resources in your returned array. **Allowable Values:**  1-10 |
| data array of objects  Conditionally returned | Array of velocity control objects that include available balances. Objects are returned as appropriate to your query. **Allowable Values:**  Valid array of one or more velocity control objects |
| data\[].**active** boolean  Conditionally returned | Indicates whether the velocity control is active. **Allowable Values:**  `true`, `false` |
| data\[].**amount\_limit** decimal  Returned | Maximum monetary sum that can be cleared within the time period defined by the `velocity_window` field. Refunds and reversals cannot exceed this limit. **Allowable Values:**  0 min **Format:** 0.00 |
| data\[].**approvals\_only** boolean  Conditionally returned | If set to `true`, only approved transactions are subject to control. If set to `false`, only declined transactions are subject to control. **Allowable Values:**  `true`, `false` |
| data\[].**association** object  Conditionally returned | Defines the group of users to which the velocity control applies. **Allowable Values:**  `card_product_token`, `user_token` |
| data\[].association.**card\_product\_token** string  Conditionally returned | Unique identifier of the card product. Pass either `card_product_token` or `user_token`, not both. **Allowable Values:**  1–36 chars |
| data\[].association.**user\_token** string  Conditionally returned | Unique identifier of the cardholder. Pass either `card_product_token` or `user_token`, not both. **Allowable Values:**  1–36 chars |
| data\[].**available** object  Returned | Specifies the available balances of the velocity controls associated with a user. This object is not returned if the velocity control window is `TRANSACTION`, because available balances do not apply to single-transaction velocity windows. **Allowable Values:**  `amount`, `days_remaining`, `uses` |
| data\[].available.**amount** decimal  Returned | Total amount of spend remaining in the velocity control. **Allowable Values:**  0 min **Format:** 0.00 |
| data\[].available.**days\_remaining** integer  Conditionally returned | Number of days remaining in the velocity control time window. **Allowable Values:**  255 char max |
| data\[].available.**uses** integer  Returned | Number of uses remaining in the velocity control. **Allowable Values:**  -1 to 100, where -1 indicates unlimited uses |
| data\[].**currency\_code** string  Returned | Three-character ISO 4217 currency code. **Allowable Values:**  Valid three-character [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) |
| data\[].**include\_cashback** boolean  Conditionally returned | If set to `true`, the cashback components of point-of-sale transactions are subject to control. **Allowable Values:**  `true`, `false` |
| data\[].**include\_credits** boolean  Conditionally returned | If set to `true`, original credit transactions (OCT) are subject to control. **Allowable Values:**  `true`, `false` |
| data\[].**include\_purchases** boolean  Conditionally returned | If set to `true`, the following transactions are subject to control: - **Account funding:** All account funding transactions - **Cashback:** Only the purchase component of cashback transactions - **Purchase transactions:** All authorizations, PIN debit transactions, and incremental transactions - **Quasi-cash:** All quasi-cash transactions - **Refunds:** All refund transactions (see [Controls to limit amount and frequency of spending](https://www.marqeta.com/docs/developer-guides/controlling-spending.md#_controls_to_limit_amount_and_frequency_of_spending) for more information) - **Reversals:** All reversal transactions **Allowable Values:**  `true`, `false` |
| data\[].**include\_transfers** boolean  Conditionally returned | If set to `true`, account-to-account transfers are subject to control. Account-to-account transfers are not currently supported. **Allowable Values:**  `true`, `false` |
| data\[].**include\_withdrawals** boolean  Conditionally returned | If set to `true`, ATM withdrawals are subject to control. **Allowable Values:**  `true`, `false` |
| data\[].**merchant\_scope** object  Conditionally returned | Defines the group of merchants to which the velocity control applies. Populate no more than one field of the `merchant_scope` object. If no fields are populated, the velocity control applies to all merchants. **Allowable Values:**  `mcc`, `mcc_group`, `mid`, or null (no value) |
| data\[].merchant\_scope.**mcc** string  Conditionally returned | Merchant Category Code (MCC). Identifies the type of products or services provided by the merchant. Enter a value to control spending on a particular type of product or service. **Allowable Values:**  1–4 chars |
| data\[].merchant\_scope.**mcc\_group** string  Conditionally returned | Token identifying a group of MCCs. Enter a value to control spending on a group of product or service types. Send a `GET` request to `/mccgroups` to retrieve MCC group tokens. **Allowable Values:**  1–36 chars |
| data\[].merchant\_scope.**mid** string  Conditionally returned | Merchant identifier (MID). Identifies a specific merchant. Enter a value to control spending with a particular merchant. Use the exact MID value as it appears in the `card_acceptor.mid` field of your Gateway JIT Funding request or transaction webhook. Marqeta performs an exact match on this value — no normalization or formatting is applied. **Allowable Values:**  1–36 chars |
| data\[].**name** string  Conditionally returned | Description of how the velocity control restricts spending, for example, "Max spend of \$500 per day" or "Max spend of \$5000 per month for non-exempt employees". **Allowable Values:**  255 char max |
| data\[].**token** string  Conditionally returned | Unique identifier of the velocity control. **Allowable Values:**  1–36 chars |
| data\[].**usage\_limit** integer  Conditionally returned | Maximum number of times a card can be used within the time period defined by the `velocity_window` field. **Allowable Values:**  -1 min  -1 to 100, where -1 indicates unlimited uses |
| data\[].**velocity\_window** string  Returned | Defines the time period to which the `amount_limit` and `usage_limit` fields apply: - **DAY** – one day; days begin at 00:00:00 UTC. - **WEEK** – one week; weeks begin Sundays at 00:00:00 UTC. - **MONTH** – one month; months begin on the first day of month at 00:00:00 UTC. - **QUARTER** – one calendar quarter; quarters begin on the first day of the quarter (January 1, April 1, July 1, or October 1). - **YEAR** – one calendar year; years begin on January 1. - **LIFETIME** – forever; time period never expires. - **TRANSACTION** – a single transaction. **Allowable Values:**  `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`, `LIFETIME`, `TRANSACTION` |
| end\_index integer  Conditionally returned | Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. **Allowable Values:**  Any integer |
| is\_more boolean  Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. **Allowable Values:**  `true`, `false` |
| start\_index integer  Conditionally returned | Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. **Allowable Values:**  Any integer |

## Sample response body

```json JSON expandable lines wrap theme={null}
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "card_3",
      "name": "Jane Doe",
      "association": {},
      "merchant_scope": {
        "mcc": "3058"
      },
      "usage_limit": 1,
      "approvals_only": true,
      "include_purchases": true,
      "include_withdrawals": true,
      "include_transfers": true,
      "include_cashback": true,
      "include_credits": false,
      "currency_code": "USD",
      "amount_limit": 296.25,
      "velocity_window": "DAY",
      "active": true,
      "available": {
        "uses": 1,
        "amount": 296,
        "days_remaining": 1
      }
    },
    {
      "token": "card_4",
      "association": {},
      "merchant_scope": {
        "mcc": "1234"
      },
      "usage_limit": 1000,
      "approvals_only": true,
      "include_purchases": true,
      "include_withdrawals": true,
      "include_transfers": true,
      "include_cashback": true,
      "include_credits": false,
      "currency_code": "840",
      "amount_limit": 500.25,
      "velocity_window": "DAY",
      "active": true,
      "available": {
        "uses": 1000,
        "amount": 500.5,
        "days_remaining": 1
      }
    }
  ]
}
```


## Related topics

- [Velocity Controls Overview](https://www.marqeta.com/docs/core-api/velocity-controls.md)
- [List velocity controls](https://www.marqeta.com/docs/core-api/velocity-controls/list-velocity-controls.md)
- [How to configure spend controls](https://www.marqeta.com/docs/how-to-configure-spend-controls.md)
- [Create velocity control](https://www.marqeta.com/docs/core-api/velocity-controls/create-velocity-control.md)
- [Update velocity control](https://www.marqeta.com/docs/core-api/velocity-controls/update-velocity-control.md)