---
title: "Ranking de retenção de valor"
method: GET
path: "/v1/rankings/retention"
tags: ["Rankings"]
---

# Ranking de retenção de valor

`GET /v1/rankings/retention`

## Request

- Base URL: `https://api.fipex.com.br`
- URL: `https://api.fipex.com.br/v1/rankings/retention`
- Auth: none declared

Os anos-modelo que mais e menos retêm valor, por tipo de veículo e
idade (1 a 10 anos), na referência mais recente.

- **Retenção** = preço FIPE atual ÷ primeiro preço que a FIPE publicou
  para aquele ano-modelo da versão (não é o preço de tabela do 0 km).
  Em reais nominais: acima de 1 significa que o preço FIPE subiu desde
  a primeira publicação (comum em carros de 5+ anos, efeito da
  inflação e da alta de usados de 2021-2022).
- **Idade** = ano civil da referência atual − ano civil da primeira
  publicação (granularidade de ano civil, não de meses): em out/2026,
  idade 1 = primeiro preço publicado em 2025.
- Entram só anos-modelo com preço na referência mais recente (o
  `mv_best_retention` mantém também versões que a FIPE parou de
  publicar, avaliadas pelo último preço) e cuja primeira publicação
  ocorreu até o próprio ano-modelo: a FIPE às vezes inclui um
  ano-modelo anos depois (Corsa 2012 publicado pela primeira vez em
  2023), e aí o "primeiro preço" já é de usado.
- Cada versão aparece no máximo uma vez por lista (no ano-modelo
  mais extremo). A mediana do grupo (`median_retention_pct`) e
  `variant_count` usam todos os anos-modelo do grupo. 0 km não entra.

## Query parameters

- `vehicle_type` 'carro' | 'moto' | 'caminhao'
- `age` integer
- `limit` integer

## Response `200`

Grupos tipo × idade com melhores e piores.

- GetRetentionRankingResponse
  - `data` RetentionRanking, required
    - `ref_year` integer, required
    - `ref_month` integer, required
    - `cohorts` RetentionCohort[], required: Por tipo (carro, moto, caminhão) e idade crescente.
      - `vehicle_type` 'carro' | 'moto' | 'caminhão', required
      - `age_years` integer, required
      - `variant_count` integer, required: Anos-modelo no grupo.
      - `median_retention_pct` number, float, required
      - `best` RetentionEntry[], required
        - `version` RankedVersion, required: Uma versão FIPE nas listas de ranking. Com o ano, forma a URL da página de veículo `/preco/<make_slug>/<model_slug>/<ano>/<fuel_acronym>`; `brand_*`/`family_*` apontam para os hubs (mesma derivação de `/v1/brands`).
          - `model_name` string, required
          - `make_slug` string, required
          - `model_slug` string, required
          - `fuel_acronym` string, required
          - `fuel_name` string, required
          - `fipe_code` string, required
          - `vehicle_type` string, required
          - `brand_slug` string, required
          - `brand_name` string, required
          - `family_slug` string, required
          - `family_name` string, required
        - `year` YearOption, required: Representa um ano disponível para um modelo. Cada opção é auto-descritiva: `value` é o seletor canônico que pode ser enviado diretamente em `/v1/prices?year=<value>`.
          - `value` string, required: Seletor canônico do ano. `"2020"` para um ano-modelo, `"zero"` para um veículo 0km/novo. Use este valor em `year=` nos endpoints de preço.
          - `is_zero_km` boolean, required: `true` quando a opção é o veículo 0km/novo (`value == "zero"`); `false` para um ano-modelo concreto. Discriminador para ordenar e rotular sem precisar interpretar `value`.
        - `first_price_cents` integer, required: Primeiro preço publicado pela FIPE para este ano-modelo.
        - `first_formatted_price` string, required
        - `first_ref_year` integer, required: Ano civil dessa primeira publicação.
        - `price_cents` integer, required: Preço na referência mais recente.
        - `formatted_price` string, required
        - `retention_pct` number, float, required: price ÷ first_price, em fração e reais nominais (`0.85` = reteve 85%).
      - `worst` RetentionEntry[], required: Da menor retenção para cima.
        - `version` RankedVersion, required: Uma versão FIPE nas listas de ranking. Com o ano, forma a URL da página de veículo `/preco/<make_slug>/<model_slug>/<ano>/<fuel_acronym>`; `brand_*`/`family_*` apontam para os hubs (mesma derivação de `/v1/brands`).
          - `model_name` string, required
          - `make_slug` string, required
          - `model_slug` string, required
          - `fuel_acronym` string, required
          - `fuel_name` string, required
          - `fipe_code` string, required
          - `vehicle_type` string, required
          - `brand_slug` string, required
          - `brand_name` string, required
          - `family_slug` string, required
          - `family_name` string, required
        - `year` YearOption, required: Representa um ano disponível para um modelo. Cada opção é auto-descritiva: `value` é o seletor canônico que pode ser enviado diretamente em `/v1/prices?year=<value>`.
          - `value` string, required: Seletor canônico do ano. `"2020"` para um ano-modelo, `"zero"` para um veículo 0km/novo. Use este valor em `year=` nos endpoints de preço.
          - `is_zero_km` boolean, required: `true` quando a opção é o veículo 0km/novo (`value == "zero"`); `false` para um ano-modelo concreto. Discriminador para ordenar e rotular sem precisar interpretar `value`.
        - `first_price_cents` integer, required: Primeiro preço publicado pela FIPE para este ano-modelo.
        - `first_formatted_price` string, required
        - `first_ref_year` integer, required: Ano civil dessa primeira publicação.
        - `price_cents` integer, required: Preço na referência mais recente.
        - `formatted_price` string, required
        - `retention_pct` number, float, required: price ÷ first_price, em fração e reais nominais (`0.85` = reteve 85%).

## Other responses

- `400`: Erro de validação (400). Usado para TODOS os erros de validação — não há 422.
- `500`: Erro interno do servidor (500).

---

[API](https://skmtc.dev/fipex/apis/api-fipex.md) · [All operations](https://skmtc.dev/fipex/apis/api-fipex/llms.txt) · [OpenAPI document](https://skmtc.dev/fipex/apis/api-fipex/revisions/800eab7da73d?raw)