---
title: "List Balances"
method: GET
path: "/balances"
tags: ["Balances"]
---

# List Balances

`GET /balances`

Retrieve a list of `Balance` resources.

## Query parameters

- `after_cursor` string
- `before_cursor` string
- `created_at.gte` string, date-time
- `created_at.lte` string, date-time
- `limit` integer
- `tags.key` string
- `tags.value` string
- `updated_at.gte` string, date-time
- `updated_at.lte` string, date-time

## Headers

- `Finix-Version` string

## Response `200`

List of `Balance` resources

- object
  - `page` Page — Details the page that's returned.
    - `limit` integer — The number of entries to return.
    - `next_cursor` string, nullable — The cursor to use for the next page of results.
  - `_embedded` object
    - `balances` Balance[]
      - `id` string — The ID of the resource.
      - `created_at` string, date-time — Timestamp of when the object was created.
      - `updated_at` string, date-time — Timestamp of when the object was last updated.
      - `available_amount` integer — The amount of funds that are currently safe to use or withdraw. This balance reflects settled funds minus any initiated outflows (such as payouts) that reduce availability immediately, even if they have not yet fully posted. Funds from incoming transactions (such as top-ups) are not included until they are finalized. *Example*: > If the posted balance is $1,000, a $500 payout is initiated, and a $600 top-up is pending, the `available_amount` is $500.
      - `currency` 'CAD' | 'USD' — ISO 4217 3-letter currency code.
      - `linked_to` string — The ID of the resource (e.g., an [`Application`](#Application)) that the `Balance` is linked to.
      - `linked_type` 'APPLICATION' — Specifies the type of resource identified in `linked_to`.
      - `pending_amount` integer — The projected balance after all in-flight transactions are finalized. This amount includes the posted balance adjusted by pending incoming and outgoing transactions, regardless of whether those funds are currently available for use. *Example*: > If the posted balance is $1,000, a $500 payout is pending, and a $600 top-up is pending, the `pending_amount` is $1,100.
      - `posted_amount` integer — The total balance derived only from finalized, settled transactions. This amount represents the authoritative ledger balance and does not include any pending incoming or outgoing transactions. *Example*: > If $1,000 has fully settled and no transactions have posted since, the `posted_amount` is $1,000, even if payouts or top-ups are currently in progress.
      - `tags` Tags, nullable — Include up to 50 `key: value` pairs to annotate requests with custom metadata. - Maximum character length for individual `keys` is 40. - Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)
      - `type` 'DISBURSEMENT' — The type of transactions stored/ledgered on the `Balance`.
      - `_links` object — An object containing link(s) relevant to the request. You can store these links for follow-up requests.
        - `self` object
          - `href` string — The path to the new `Balance` resource.
  - `_links` object
    - `self` Self — Link to the resource that was used in the request.
      - `href` string
    - `next` Next — Link to the next page of entries.
      - `href` string

## Other responses

- `401` — Unauthorized. Authentication is required and has failed or has not been provided.
- `403` — Forbidden. The client is authenticated but does not have permission to access the resource.
- `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted.
- `422` — Unprocessable Entity. One or more query parameters were syntactically valid but could not be processed.

---

[API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)