# List balances

## ▶️ Usage

With the List Balances method, you can:
  
  1.  List balances related to a specific  (using the  query parameter).
  2.  List balances related to a specific  and  (using the  and  query parameters).
  2. Get the details of a specific  (using the  query parameter).

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the  query parameter to increase the number of items returned to a maximum of 1000 items. You can use the  query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.
    
## 🚨 Deprecated Fields

This resource may return deprecated fields. In the response documentation you may see that a field has been marked as . This means that this field is no longer maintained by the Belvo team. You may still receive data for this field depending on the institution, however, you should not rely on this field.


Endpoint: GET /api/br/balances/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `link` (string, required)
    The  you want to filter by.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `account` (string)
    The  you want to filter by.

ℹ️ We highly recommend adding either the  or the  filters in order to improve your performance.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `id` (string)
    Return information only for this resource .
    Example: "24ccab1d-3a86-4136-a6eb-e04bf52b356f"

  - `link__in` (array)
    Return results only for these s.
    Example: ["5722d0ba-69d7-42dc-8ff5-33767b83c5d6"]

  - `account__in` (array)
    Return results only for these s.
    Example: ["85b77707-90ef-46fd-9059-5a757f24247a"]

  - `id__in` (array)
    Return information for these resource s.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `omit` (string)
    Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.

  - `fields` (string)
    Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.

  - `collected_at` (string)
    Return items that were retrieved from the institution on this date ( or full  timestamp).
    Example: "2022-05-01"

  - `collected_at__gt` (string)
    Return items that were retrieved from the institution after this date ( or full  timestamp).
    Example: "2022-05-05"

  - `collected_at__gte` (string)
    Return items that were retrieved from the institution after or on this date ( or full  timestamp).
    Example: "2022-05-04"

  - `collected_at__lt` (string)
    Return items that were retrieved from the institution before this date ( or full  timestamp).
    Example: "2022-04-01"

  - `collected_at__lte` (string)
    Return items that were retrieved from the institution before or on this date ( or full  timestamp).
    Example: "2022-03-30"

  - `collected_at__range` (array)
    Return items that were retrieved from the institution between two dates ( or full  timestamp).
    Example: ["2022-05-04"]

  - `created_at` (string)
    Return items that were last updated in Belvo's database on this date (in  format).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Return items that were last updated in Belvo's database after this date (in  format).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Return items that were last updated in Belvo's database after or on this date (in  format).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Return items that were last updated in Belvo's database before this date (in  format).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Return items that were last updated in Belvo's database before or on this date (in  format).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Return accounts that were last updated in Belvo's database between two dates (in  format).
    Example: ["2022-03-03"]

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is .

In our documentation example, we use  as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example,  or ).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is .

  - `results` (array)
    An array of balance objects.

  - `results.id` (string, required)
    The unique identifier created by Belvo used to reference the current balance.
    Example: "0b94bdf9-3719-43a9-81e7-be95d2318595"

  - `results.link` (string, required)
    The unique identifier of the link that this balance belongs to.
    Example: "0b94bdf9-3719-43a9-81e7-be95d2318595"

  - `results.account_id` (string, required)
    The Belvo  that this balance belongs to.
    Example: "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321"

  - `results.account_internal_identification` (string, required)
    The institution's internal identification for the account.
    Example: "92792126019929279212650822221989319252576"

  - `results.collected_at` (string, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2024-05-21T08:32:00Z"

  - `results.created_at` (string, required)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2024-05-21T08:32:00Z"

  - `results.last_updated_at` (string, required)
    The ISO-8601 timestamp of when this balance was last updated by the institution.

> 🚧 Warning
>
> The  parameter depends on how the institution processes (or stores) data. In the case that the institution stores data synchronously (that is, as soon as a transaction occurs, the balance us updated), then the  will reflect the balance in near real time. In the case that the institution stores data asynchronously (that is, it retrieves data in bulk and then updates the balance), the balance information can refer to hours or days ago. Additionally, in the case that the institution cannot provide the specific time (due to an internal error), the institution may provide an overall time where they last refreshed the account and balance information.
    Example: "2021-05-21T08:30:00Z"

  - `results.currency` (string, required)
    The three-letter currency code (ISO-4217).
    Example: "USD"

  - `results.available` (number, required)
    The available account balance.
    Example: 1000.02

  - `results.blocked` (number, required)
    The amount that is currently blocked due to, for example, pending transactions.
    Example: 1000.02

  - `results.automatically_invested` (number, required)
    The amount that is automatically invested (as agreed upon with the institution).
    Example: 1000.02

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For  errors, the description is:
  
  - .
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For  errors, the description is:
  
  - .
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For  errors, the description is:
  
  - .
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"