---
title: "List employment metrics"
method: GET
path: "/api/employment-metrics/"
tags: ["Employment Metrics"]
---

# List employment metrics

`GET /api/employment-metrics/`

## ▶️ Usage

With the List Employment Metrics method, you can:

1. List employment metrics related to a specific `link.id` (using the `link` query parameter).
2. Get the details of a specific `employment-metric.id` (using the `id` query parameter).
3. **[Not Recommended]** List all employment metrics 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

## 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` EmploymentMetric[] — Array of employment metric 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.
    - `collected_at` string, date-time, required — The ISO-8601 timestamp when the data point was collected.
    - `created_at` string, date-time, required — The ISO-8601 timestamp of when the data point was created in Belvo's database.
    - `updated_at` string, date-time, nullable, required — The ISO-8601 timestamp of when the employment metrics calculation was last updated.
    - `reference_date` string, date, nullable, required — The reference_date your provided in your request. If you didn't provide one, this field will return `null`, indicating that the calculations are performed up until the date of the request. **Note:** All calculations are relative to this date.
    - `age` integer, required — The age of the individual.
    - `current_status` 'EMPLOYED' | 'RETIRED' | 'UNEMPLOYED' | 'null', required — Indicates the employment status of the individual. We return one of the following responses: - `EMPLOYED` - `RETIRED` - `UNEMPLOYED` - `null`
    - `current_employer_count` integer, nullable, required — The number of employers the individual has right now.
    - `base_salary_last` number, float, nullable, required — The user's latest base salary. If `current_status` is `EMPLOYED`, this is the user's current base salary.
    - `weeks_employed_last_job` number, float, nullable, required — The number of weeks the user was employed in their last job. If `current_status` is `EMPLOYED`, then this field indicates the number of weeks the user has been employed with his current job.
    - `weeks_since_last_job` number, float, nullable, required — The number of weeks since their last job. If the value of this field is `0`, this indicates that the user is currently employed.
    - `weeks_employed_total` number, float, nullable, required — The total number of weeks the user has been employed, according to the institution. > **Note:** > > In the case that the user is employed at two or more places at the same time, we still calculate those weeks as one week. For example, if a user has three concurrent jobs for a month, this is calculated as 4 weeks.
    - `weeks_with_multiple_employers` number, float, nullable, required — The number of the weeks that the individual has had more than one employer at the same time.
    - `employer_count` integer, nullable, required — The total number of employers the user has had. Useful to indicate employment stability over the course of their lifetime.
    - `unique_employer_count` integer, nullable, required — The number of unique employers that the individual has had. > **Note:** > > If the user left one company and returned, for example, six months later to the same company, this is counted as one employer.
    - `employers_per_year` number, float, nullable, required — Number of employers per year. Useful to indicate employment stability over the course of a year. > **Note:** > > If the user left one company and returned, for example, six months later to the same company, this is counted as one employer.
    - `weeks_between_jobs` number, float, nullable, required — The total number of weeks the individual was unemployed.
    - `max_weeks_between_jobs` number, float, nullable, required — The maximum number of weeks that the individual was unemployed.
    - `increases_last_job` integer, nullable, required — The total number of salary increases the user had in their last job. If `current_status` is `EMPLOYED`, this refers to the user's current job. > **Note:** > > For all salary increases or decreases, we only take into account those where the change in salary is greater than 2%.
    - `decreases_last_job` integer, nullable, required — The total number of salary increases the user had in their last job. If `current_status` is `EMPLOYED`, this refers to the user's current job.
    - `increases_after_change` integer, nullable, required — The total number of salary increases between the individual's penultimate job and the last (or current) job.
    - `decreases_after_change` integer, nullable, required — The total number of salary decreases between the individual's penultimate job and the last (or current) job.
    - `increases_overall` integer, nullable, required — The total number of salary increases throughout the individual's working career.
    - `decreases_overall` integer, nullable, required — The total number of salary decreases throughout the individual's working career.
    - `increases_1y` integer, nullable, required — The total number of salary increases throughout the individual's last year (YTD).
    - `decreases_1y` integer, nullable, required — The total number of salary decreases throughout the individual's last year (YTD).
    - `increases_3y` integer, nullable, required — The total number of salary increases throughout the individual's last three years. > **Note:** > > If the individual's working career is less than three years, we return `null`.
    - `decreases_3y` integer, nullable, required — The total number of salary decreases throughout the individual's last three years. > **Note:** > > If the individual's working career is less than three years, we return `null`.
    - `increases_5y` integer, nullable, required — The total number of salary increases throughout the individual's last five years. > **Note:** > > If the individual's working career is less than five years, we return `null`.
    - `decreases_5y` integer, nullable, required — The total number of salary decreases throughout the individual's last five years. > **Note:** > > If the individual's working career is less than five years, we return `null`.
    - `yearly_change_1y` number, float, nullable, required — The individual's salary percentage change for the last year (YTD).
    - `yearly_change_3y` number, float, nullable, required — The individual's salary percentage change for the last three years. > **Note:** > > If the individual's working career is less than three years, we return `null`.
    - `yearly_change_5y` number, float, nullable, required — The individual's salary percentage change for the last five years. > **Note:** > > If the individual's working career is less than five years, we return `null`.
    - `min_monthly_salary_1y` number, float, nullable, required — The individual's minimum monthly salary for the last year.
    - `min_monthly_salary_3y` number, float, nullable, required — The individual's minimum monthly salary for the last three years.
    - `min_monthly_salary_5y` number, float, nullable, required — The individual's minimum monthly salary for the last five years.
    - `average_monthly_salary_1y` number, float, nullable, required — The individual's average monthly salary for the last year.
    - `average_monthly_salary_3y` number, float, nullable, required — The individual's average monthly salary for the last three years.
    - `average_monthly_salary_5y` number, float, nullable, required — The individual's average monthly salary for the last five years.
    - `max_monthly_salary_1y` number, float, nullable, required — The individual's maximum monthly salary for the last year.
    - `max_monthly_salary_3y` number, float, nullable, required — The individual's maximum monthly salary for the last three years.
    - `max_monthly_salary_5y` number, float, nullable, required — The individual's maximum monthly salary for the last five years.

## 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/versions/3423c786ece5/schema)