---
title: "List incomes"
method: GET
path: "/api/incomes/"
tags: ["Incomes"]
---

# List incomes

`GET /api/incomes/`

## ▶️ Usage

With the List Incomes method, you can:

1. List incomes related to a specific `link.id` (using the `link` query parameter).
2. Get the details of a specific `income.id` (using the `id` query parameter).
3. **[Not Recommended]** List all incomes related to your Belvo account (without using any query parameters).

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the `page_size` query parameter to increase the number of items returned to a maximum of 1000 items. You can use the `page` query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our <a href="https://developers.belvo.com/docs/belvo-pagination-tips" target="_blank">Pagination Tips</a> article.

## 🔦 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 <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> article.

## Query parameters

- `link` string, uuid
- `page_size` integer
- `page` integer
- `link__in` string[]
- `omit` string
- `fields` string
- `account` string, uuid
- `account__in` string[]

## Response `200`

Ok

- object
  - `count` integer — The total number of results in your Belvo account.
  - `next` string, uri, nullable — 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 `null`. In our documentation example, we use `{endpoint}` as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, `accounts` or `owners`).
  - `previous` string, uri, nullable — The URL to the previous page of results. If there is no previous page, the value is `null`.
  - `results` Income[] — Array of income objects.
    - `id` string, uuid, required — Belvo's unique identifier for the current item.
    - `link` string, uuid, nullable, required — The `link.id` the data belongs to.
    - `created_at` string, date-time, required — The ISO-8601 timestamp of when the data point was created in Belvo's database.
    - `income_streams` IncomeStreamsBody[], required — An array of enriched income stream objects.
      - `account_id` string, required — Unique ID for the bank account to be verified for income streams.
      - `income_type` 'SALARY' | 'GOVERNMENT' | 'INTEREST' | 'RENT' | 'RETIREMENT' | 'FREELANCE' | 'ALTERNATIVE_INCOME' | 'TRANSFER' | 'DEPOSIT' | 'UNKNOWN', required — The type of income used in the calculations. We return one of the following enum values: - `SALARY` - `GOVERNMENT` - `INTEREST` - `RENT` - `RETIREMENT` - `FREELANCE` - `ALTERNATIVE_INCOME` - `TRANSFER` - `DEPOSIT` - `UNKNOWN`
      - `frequency` 'MONTHLY' | 'FORTNIGHTLY' | 'WEEKLY' | 'IRREGULAR' | 'SINGLE', required — How often the income is received. We return one of the following enum values: - `MONTHLY` - For transactions that occur once per month. - `FORTNIGHTLY` - For transactions that occur once every two weeks. - `WEEKLY` - For transactions that occur once per week. - `IRREGULAR` - For transactions that do not occur on a defined frequency pattern. - `SINGLE` - For transactions that occur only once and do not repeat.
      - `monthly_average` number, float, required — The average amount of income received from the source over `periods_with_income`.
      - `monthly_median` number, float — The median amount of income received from the source over within a natural month.
      - `average_income_amount` number, float, required — The average income transaction amount from the source.
      - `last_income_amount` number, float, required — The amount of the most recent income received from the source.
      - `currency` string, required — The three-letter currency code of the income. For example: • 🇧🇷 BRL (Brazilian Real) • 🇨🇴 COP (Colombian Peso) • 🇲🇽 MXN (Mexican Peso)
      - `last_income_description` string, required — The description of the most recent income from the stream.
      - `last_income_date` string, date, required — The date when the most recent income from the stream was received, in `YYYY-MM-DD` format.
      - `stability` number, float, nullable, required — The stability of the income based on its amount, with a range from 0 to 1, where 1 represents perfect stability. **Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.
      - `regularity` number, float, nullable, required — The regularity of the income based in its frequency, with a range from 0 to 1, where 1 represents perfect regularity. **Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.
      - `trend` number, float, nullable, required — The income trend during a period of time calculated between last income and first income received, where: - a negative float means that the income trend is decreasing during the time period. - a positive float means that the income trend is increasing during the time period. **Note:** For transactions with `frequency`=`SINGLE`, this value returns `null`.
      - `lookback_periods` integer, required — Number of period units (based on *rolling months*) used to generate insights and calculations. **Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.
      - `full_periods` integer, required — Number of period units (based on *rolling months*) with data to perform calculations. **Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.
      - `periods_with_income` integer, required — Number of period units (based on *rolling months*) with at least one income available. **Note:** A *rolling month* is a period of 30 days. For example, 2023-01-15 to 2023-02-15.
      - `number_of_incomes` integer, required — Number of income transactions over the `lookback_periods`.
      - `confidence` 'HIGH' | 'MEDIUM' | 'LOW', required — Belvo's level of confidence for future incomes. We return one of the following enum values: - `HIGH` - `MEDIUM` - `LOW`
    - `income_source_type` 'BANK', required — The type of source we generate income insights from. We return one of the following enum values: - `BANK`
    - `first_transaction_date` string, date, nullable, required — The date when the first transaction occurred, in `YYYY-MM-DD` format.
    - `last_transaction_date` string, date, required — The date when when the last transaction occurred, in `YYYY-MM-DD` format.
    - `best_working_day_to_charge` integer, required — The best working day of the month to charge the user.
    - `good_working_days_to_charge` integer[], required — Additional working days that have been identified as good days to charge the user.
    - `number_of_income_streams` integer, required — Number of total income streams analized.
    - `monthly_average` number, float, required — Average amount of income received per month across all the accounts for the specific user.
    - `monthly_average_regular` number, float, required — Average amount of regular income (with a frequency of `MONTHLY`, `FORTNIGHTLY`, or `WEEKLY`) received per month for the specific user.
    - `monthly_average_irregular` number, float, required — Average amount of irregular income (with a frequency of `SINGLE` or `IRREGULAR`) received per month for the specific user.
    - `monthly_average_low_confidence` number, float, required — Average amount of income received per month for the specific user with `LOW` confidence.
    - `monthly_average_medium_confidence` number, float, required — Average amount of income received per month for the specific user with `MEDIUM` confidence.
    - `monthly_average_high_confidence` number, float, required — Average amount of income received per month for the specific user with `HIGH` confidence.
    - `total_income_amount` number, float, required — Total amount of all income received for the specific user.
    - `total_regular_income_amount` number, float, required — Total amount of regular income (with a frequency of `MONTHLY`, `FORTNIGHTLY`, `WEEKLY`) for the specific user.
    - `total_irregular_income_amount` number, float — Total amount of irregular income (with a frequency of `SINGLE` or `IRREGULAR`) for the specific user.
    - `total_low_confidence` number, float, required — Total amount of income for the specific user with `LOW` confidence.
    - `total_medium_confidence` number, float, required — Total amount of income for the specific user with `MEDIUM` confidence.
    - `total_high_confidence` number, float, required — Total amount of income for the specific user with `HIGH` confidence.

## Other responses

- `401` — Unauthorized
- `403` — Access to Belvo API denied
- `404` — Not Found Error
- `408` — Request Timeout
- `500` — Unexpected Error

---

[API](https://skmtc.net/belvo/apis/belvo-api-docs.md) · [All operations](https://skmtc.net/belvo/apis/belvo-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/belvo/belvo-api-docs/revisions/3423c786ece5/schema)