Pular para o conteúdo principal
Cole no ChatGPT/Claude e peça para resumir/gerar SDK.

Concentração de cotistas

GET
/traded-funds/[fundIdentifier]/unitholders/concentration

Retorna a distribuição dos cotistas de um FII ou Fiagro por faixa de participação nas cotas, conforme o informe anual do fundo. Cada documento traz as oito faixas do informe, os totais do fundo e os limites do índice de concentração (HHI).

Quando usar​

  • Saber se um fundo é pulverizado ou tem poucos cotistas grandes
  • Separar fundos de um cotista só (exclusivos) dos fundos de varejo
  • Medir a fatia de pessoas físicas e de institucionais em cada faixa

Parâmetros de requisição​

ParâmetroLocalDescriçãoObrigatório
[fundIdentifier]URLIdentificador do fundo: ticker (ex.: HGLG11), symbol (ex.: HGLG) ou company_id numérico.Obrigatório
reference_dateQueryISO 8601. Filtra pela data de referência (considera o dia inteiro).Opcional
publish_dateQueryISO 8601. Retorna apenas documentos publicados após a data informada.Opcional
retrieval_dateQueryISO 8601. Retorna apenas documentos coletados após a data informada.Opcional
latest_by_reference_dateQuerySe true, mantém apenas o documento publicado mais recentemente por data de referência.Opcional
limitQueryQuantidade de resultados. Mín.: 1, máx.: 500. Padrão: 50.Opcional
offsetQueryQuantidade de resultados a pular. Mín.: 0. Padrão: 0.Opcional

Resposta​

CódigoDescrição
200Retorna os documentos de concentração do fundo, do mais recente para o mais antigo.
400Parâmetros ausentes ou inválidos.
401Não autorizado.
404Fundo não encontrado.

Formato da resposta​

CampoTipoDescrição
reference_datestring (ISO 8601)Data de referência do informe anual.
publish_datestring (ISO 8601)Data de publicação do informe na fonte.
retrieval_datestring (ISO 8601)Data/hora em que a Partnr coletou o informe.
unitholder_distributionarrayAs faixas de participação do informe (ver abaixo).
total_unitholdersnumber | nullSoma dos cotistas das faixas.
total_unitsnumber | nullSoma das cotas das faixas.
top_band_concentrationstring | nullband_id da faixa que detém a maior parte das cotas.
hhi_minnumber | nullMenor HHI que as faixas permitem, de 0 a 10.000.
hhi_maxnumber | nullMaior HHI que as faixas permitem, de 0 a 10.000.
sourcesarrayLista de fontes oficiais do documento.

Estrutura de unitholder_distribution[]​

CampoTipoDescrição
band_idstringFaixa de participação: BAND_0_5, BAND_5_10, BAND_10_15, BAND_15_20, BAND_20_30, BAND_30_40, BAND_40_50 ou BAND_50_PLUS.
band_descriptionstringFaixa em texto (ex.: 0%-5%, >50%).
unitholders_countnumberCotistas cuja participação está na faixa.
units_countnumberCotas que esses cotistas detêm juntos.
ownership_percentagenumberParte das cotas do fundo que a faixa detém, em fração: 100% = 1, 45% = 0.45.
retail_ownership_percentagenumberParte das cotas do fundo em pessoas físicas da faixa, em fração.
institutional_ownership_percentagenumberParte das cotas do fundo em pessoas jurídicas e institucionais da faixa, em fração.

Os três campos de participação vêm em fração. Quando o fundo preenche o informe em percentual (algum valor acima de 1), os valores são divididos por 100 (ex.: 89.67 no informe vira 0.8967).

Índice de concentração (HHI)​

O HHI é a soma dos quadrados da participação de cada cotista, em uma escala de 0 a 10.000. Um fundo com um cotista só tem HHI 10.000. Um fundo com muitos cotistas pequenos tem HHI perto de zero.

O informe anual não lista os cotistas. Ele informa quantos cotistas há em cada faixa e quanto das cotas eles detêm juntos. Com esses dados não é possível calcular o HHI exato, mas é possível calcular os dois limites dele:

CampoComo é calculado
hhi_minTodos os cotistas de cada faixa com a mesma participação.
hhi_maxEm cada faixa, o maior número possível de cotistas no limite superior da faixa.

O HHI verdadeiro do fundo está entre hhi_min e hhi_max. A distância entre os dois nunca passa de 500 pontos.

Fundohhi_minhhi_maxLeitura
HGLG11 (2025), 524.001 cotistas, todos na faixa 0%-5%0,02500Pulverizado.
MXRF11 (2025), dois cotistas com 10,3% juntos53500Pulverizado, com dois cotistas relevantes.
Fundo com um cotista10.00010.000Exclusivo.
Quando hhi_min e hhi_max são null

Os dois campos vêm null quando as faixas do próprio informe se contradizem e não permitem calcular limites. Isso ocorre em um destes casos:

  • o informe não tem nenhuma faixa preenchida;
  • uma faixa tem cotas e nenhum cotista;
  • uma faixa acima de 5% tem cotistas e nenhuma cota;
  • a participação média por cotista de uma faixa fica fora dos limites da faixa (por exemplo, um cotista com 50% das cotas na faixa 10%-15%);
  • as faixas não somam 100% das cotas (tolerância de 1 ponto percentual).

Nesses documentos, o número de cotistas e o de cotas vêm como o fundo os informou, e as participações passam pela mesma conversão para fração. Como o informe é inconsistente, as participações podem não somar 1. Em poucos informes preenchidos com erro, um valor pode ficar acima de 1. Use-os com cuidado.

Exemplo​

GET /traded-funds/MXRF11/unitholders/concentration?limit=1

[
{
"reference_date": "2025-12-31T00:00:00.000Z",
"publish_date": "2026-03-31T12:27:00.000Z",
"retrieval_date": "2026-05-29T02:55:49.780Z",
"unitholder_distribution": [
{
"band_id": "BAND_0_5",
"band_description": "0%-5%",
"unitholders_count": 357620,
"units_count": 113816871,
"ownership_percentage": 0.896719243313288,
"retail_ownership_percentage": 0.832324065753309,
"institutional_ownership_percentage": 0.0643951775599791
},
{
"band_id": "BAND_5_10",
"band_description": "5%-10%",
"unitholders_count": 2,
"units_count": 13109000,
"ownership_percentage": 0.103280756686712,
"retail_ownership_percentage": 0,
"institutional_ownership_percentage": 0.103280756686712
}
],
"total_unitholders": 357622,
"total_units": 126925871,
"top_band_concentration": "BAND_0_5",
"hhi_min": 53.357058420294585,
"hhi_max": 500.2152672887481,
"sources": [
{
"visualization_url": "https://fnet.bmfbovespa.com.br/fnet/publico/exibirDocumento?id=...",
"download_url": null,
"published_at": "2026-03-31T12:27:00.000Z",
"retrieved_at": "2026-05-29T02:55:49.780Z",
"name": "Informe Anual Estruturado"
}
]
}
]

O exemplo mostra só as duas faixas com cotistas. A resposta traz as oito faixas; as vazias vêm com zero.