---
title: "Lista os períodos de referência"
method: GET
path: "/v1/reference-periods"
tags: ["Períodos de Referência"]
---

# Lista os períodos de referência

`GET /v1/reference-periods`

## Request

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

Recupera uma lista paginada de períodos de referência com filtros opcionais.

**Filtros Disponíveis:**
- `year`: Filtro de ano com operadores `=`, `!=`, `>`, `<`, `>=`, `<=`, `IN`, `NOT IN`, `TO`.
- `month`: Filtro de mês com operadores `=`, `!=`, `>`, `<`, `>=`, `<=`, `IN`, `NOT IN`, `TO`.

**Ordenação:**
- `year`: Ordena pelo ano (padrão: descendente).
- `month`: Ordena pelo mês (padrão: descendente).

## Query parameters

- `page` integer
- `limit` integer
- `order_by` union
  - string
  - string[]
- `year` integer
- `month` integer
- `filters` FilterExpression[]
  - `field` string, required: Nome do campo para filtrar.
  - `op` '=' | '!=' | '>' | '<' | '>=' | '<=' | 'CONTAINS' | 'NOT CONTAINS' | 'IN' | 'NOT IN' | 'TO' | 'IS NULL', required: Operador do filtro.
  - `value` string: Valor do filtro (o tipo depende do campo e do operador). Para IN/NOT IN/TO use vírgula como separador.
  - `negate` boolean: Se deve negar a condição do filtro.
  - `condition` 'AND' | 'OR': Condição lógica para combinar com outros filtros.

## Response `200`

Períodos de referência obtidos com sucesso.

- ListReferencePeriodsResponse
  - `data` ReferencePeriod[], required
    - `id` string, uuid, required
    - `month` integer, required: Mês de referência (1-12).
    - `month_name` string, required: Nome do mês por extenso (ex: "Junho").
    - `year` integer, required: Ano de referência.
    - `price_count` integer, required: Quantidade de preços publicados nesta referência (estoque).
    - `added` integer, nullable: Combinações veículo/ano/combustível presentes nesta referência e ausentes na referência anterior (fluxo). Ausente (null) na referência mais antiga do dataset, que não tem antecessora — nesse caso o valor nunca é 0.
    - `removed` integer, nullable: Combinações veículo/ano/combustível presentes na referência anterior e ausentes nesta (fluxo). Ausente (null) na referência mais antiga do dataset, que não tem antecessora — nesse caso o valor nunca é 0.
    - `fipe_id` integer, required: Número de sequência de publicação da própria FIPE. Chave monotônica que ordena as referências (prefira-a a tuplas (year, month)).
  - `pagination` Pagination, required
    - `total` integer, required: Número total de itens.
    - `limit` integer, required: Itens por página.
    - `page` integer, required: Número da página atual.
    - `pages` integer, required: Número total de páginas (mínimo 1, mesmo quando total=0).

## 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)