---
title: "Maiores instituições por métrica numa data-base"
method: GET
path: "/v1/bcb/ranking"
tags: ["BCB"]
---

# Maiores instituições por métrica numa data-base

`GET /v1/bcb/ranking`

## Request

- Base URL: `https://api.balancos.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.balancos.ai/v1/bcb/ranking`
- Auth: HTTP bearer

## Query parameters

- `metrica` string, required: `ativo`, `carteira`, `captacoes`, `patrimonio`, `lucro` (acumulado no semestre) ou `basileia`.
- `data_base` string: Data-base `AAAAMM` (mês 03, 06, 09 ou 12); padrão: a última.
- `nivel` string: `padrao` (uma linha por grupo, no nível padrão), `individual`, `financeiro` ou `prudencial`.
- `uf` string: Sigla da UF da sede; opcional.
- `tipo` string: Código do tipo de instituição (TI); opcional.
- `consolidado_bancario` string: Código TCB; opcional.
- `limite` integer: Instituições por página, de 1 a 100.
- `inicio` integer: Posição do primeiro item da página, a partir de 1.

## Response `200`

Página do ranking (até 100 por chamada; `proximo_inicio` quando há mais); `unidade` diz se `valor` é em reais ou fração.

- AppsApiBcbModelosEnvelopeRanking
  - `dados` AppsApiBcbModelosRanking, required
    - `data_base` string, required
    - `data_referencia` string, required
    - `nivel` string, required
    - `metrica` string, required
    - `unidade` string, required
    - `inicio` integer, required
    - `total` integer, nullable, required
    - `proximo_inicio` integer, nullable, required
    - `instituicoes` InstituicaoRanking[], required
      - `posicao` integer, required
      - `nivel` string, required
      - `codinst` string, required
      - `nome` string, nullable, required
      - `cnpj` string, nullable, required
      - `tipo` Codigo, required
        - `codigo` string, required
        - `nome` string, nullable, required
      - `consolidado_bancario` Codigo, required
        - `codigo` string, required
        - `nome` string, nullable, required
      - `uf` string, nullable, required
      - `valor` union, required
        - integer
        - number
      - `empresa` EmpresaResumo, required: `{razao_social, slug, link}` — o ponteiro leve usado dentro de balanços, DREs e documentos.
        - `razao_social` string, required
        - `slug` string, required
        - `link` string, required
  - `meta` Meta, required
    - `versao` string
    - `release` string
    - `dados_atualizados_em` string, nullable, required
    - `requisicao_id` string, required

## Other responses

- `400`: `parametro_invalido` (métrica, nível, data-base, limite) ou `requisicao_invalida`.
- `401`: `chave_invalida` — Bearer ausente, malformado, inexistente ou revogado.
- `404`: `data_base_nao_encontrada` — data-base sem dado no gold.
- `429`: `limite_excedido` (cota da conta) ou `limite_ip` (piso por IP).
- `503`: `indisponivel` — gold ou Supabase fora, ou falha ao concluir a medição.

---

[API](https://skmtc.dev/balancos/apis/balancos-ai-api-publica.md) · [All operations](https://skmtc.dev/balancos/apis/balancos-ai-api-publica/llms.txt) · [OpenAPI document](https://skmtc.dev/balancos/apis/balancos-ai-api-publica/revisions/389d7f383cb5?raw)