DataBolsa docs
Referência da APIDados de mercadoObjects

Consulta relações no grafo inteiro, sem partir de um objeto

A travessia por objeto responde 'com quem ESTE se relaciona'. Esta responde sobre o conjunto: todas as relações de um tipo, opcionalmente presas a um lado (`from_id`/`to_id`) ou restritas por tipo de objeto (`from_kind`/`to_kind`). Para contagem e extremos, prefira `/links/stats` — não pagina.

GET
/v1/objects/links
AuthorizationBearer <token>

In: header

Query Parameters

cursor?string
limit?integer
Default100
Range1 <= value <= 1000
total?string

true = inclui meta.total (contagem do universo filtrado). Custa uma consulta a mais.

rel?string

O verbo da relação. from é sempre quem PRATICA a ação.

measures e forecasts são coisas diferentes e foram separados em 20/08/2026. bcb_sgs:433 --measures--> IPCA é a inflação que OCORREU; bcb_focus:ipca:2027 --forecasts--> IPCA é a que se espera. Enquanto dividiam um verbo só, as 45 arestas do IPCA saíam com source, shape e confidence idênticos — 4 mediam e 41 projetavam — e quem atravessasse 'a inflação medida' recebia 41 previsões junto, sem erro e com tudo plausível.

mentions liga o EVENTO ao objeto citado, e a ponta do objeto vem carimbada pelo detector na escrita — não casada por nome em tempo de consulta. magnitude carrega quantos objetos aquele evento cita: 1 a 3 é uma notícia sobre eles, 65 é um apanhado de mercado, e confidence cai para low a partir de 9.

covers diz de que PAÍS a série falaworld_bank:NY.GDP.MKTP.CD:DE cobre a Alemanha. Só onde a fonte declara o país, e não onde se poderia deduzi-lo de quem publica: o Banco Central publica a PTAX, que é sobre o par BRL/USD e não sobre o Brasil.

produces liga PAÍS a commodity mineral, e é a primeira aresta entre dois tipos que antes não tocavam nada: país e commodity eram objetos que resolviam por nome, apareciam no censo e não tinham uma única relação. magnitude é a PARTICIPAÇÃO NO TOTAL MUNDIAL em pontos percentuais, e não a quantidade — tonelada de nióbio e quilate de diamante não se comparam, participação se compara sempre. Nula onde a própria fonte marca as bases como não somáveis, e nas commodities com mais de um agregado (cobre tem produção de mina e de refino) só o recorte que mais países reportam carrega número. NÃO liga empresa a produto: os produtores que o USGS publica são países, e ligar a Vale ao minério de ferro por semelhança de nome seria vínculo inventado.

rates é a primeira relação vinda de EXTRAÇÃO, não de formulário: a nota sai do relatório da própria agência, lido por LLM, e a aresta carrega o magnitude como o NOTCH da nota com magnitude_unit na escala (national_br ou global). Notch de escalas diferentes não se compara — AAA nacional é relativo ao teto soberano.

manages e administers também são coisas diferentes. O GESTOR decide a carteira; o ADMINISTRADOR FIDUCIÁRIO é o responsável legal — constitui o fundo, registra na CVM, calcula e divulga a cota e contrata os demais prestadores. Quase sempre são casas distintas, e a concentração é oposta: o maior administrador responde por 7.350 fundos.

Value in"issued" | "assigned_to" | "holds" | "manages" | "administers" | "custodies" | "audits" | "same_owner" | "shareholder_of" | "indexed_to" | "rates" | "mentions" | "measures" | "forecasts" | "contains" | "member_of" | "exposed_to_issuer" | "succeeded_by" | "produces" | "covers"
from_kind?string

Restringe o tipo do objeto que PRATICA o verbo.

Value in"company" | "equity_security" | "fund" | "service_provider" | "instrument" | "index" | "crypto_asset" | "commodity" | "country" | "indicator" | "data_series" | "offering" | "fund_share_class" | "market_event"
to_kind?string

Restringe o tipo do objeto que RECEBE.

Value in"company" | "equity_security" | "fund" | "service_provider" | "instrument" | "index" | "crypto_asset" | "commodity" | "country" | "indicator" | "data_series" | "offering" | "fund_share_class" | "market_event"
from_subkind?string

O mesmo recorte um nível abaixo: arestas de FIDC para cedente, e não de fundo.

to_subkind?string
from_id?string
to_id?string
at?string

Corte temporal (AAAA-MM-DD). SEM ele a resposta é 'quem JÁ se relacionou', não 'quem se relaciona' — a diferença é grande e silenciosa.

O RECORTE DEPENDE DA FORMA DO VERBO (shape, publicado em listObjectRelations):

  • event (issued, indexed_to, succeeded_by): aconteceu numa data e não deixa de ter acontecido — entra tudo que ocorreu até at, sem limite superior. Aresta sem data declarada NÃO entra: o registro de ações não publica data de emissão, e afirmar que ela já existia numa data passada é afirmação que a fonte não faz.
  • snapshot (holds, contains, assigned_to, exposed_to_issuer): retrato por competência, e nenhum retrato se afirma válido depois de ser tirado. A janela é contida (relação que saiu e voltou não aparece no buraco), e at mais recente que a última competência recua até ela — a resposta diz em meta.as_of qual data foi realmente aplicada. Cada verbo tem a competência DELE: holds fecha no trimestre da CDA, contains no pregão do dia.
  • static (manages, administers, custodies, audits, same_owner, shareholder_of, measures, forecasts): o registro publica só o VIGENTE — 111.729 arestas sem início declarado. Com o verbo preso em rel, at no passado responde 400 em vez de devolver o gestor de hoje como gestor de 2020. Sem verbo preso, essas arestas são removidas do conjunto e meta.excluded_shapes diz que foram.

AS IRMÃS NÃO COMPARTILHAM O DEFAULT. Sem at: esta operação, listGlobalLinks, intersectObjects e findObjectPaths respondem 'quem JÁ se relacionou'; getObjectLinkStats resume o retrato VIGENTE (última competência do próprio conjunto); traverseObjectPath atravessa o retrato vigente POR SUJEITO em cada salto. As diferenças são deliberadas — histórico acumulado, resumo e travessia respondem perguntas distintas — e cada rota declara a sua no próprio at. Medido em 23/08/2026: 1 aresta no resumo contra 100+ na listagem, para o mesmo objeto, os dois certos.

Match^\d{4}-\d{2}-\d{2}$

Response Body

curl -X GET "https://api.databolsa.com/v1/objects/links?cursor=string&limit=100&total=string&rel=issued&from_kind=company&to_kind=company&from_subkind=string&to_subkind=string&from_id=string&to_id=string&at=string"
{
  "data": [
    {
      "rel": "string",
      "shape": "event",
      "from_id": "string",
      "to_id": "string",
      "source": "string",
      "valid_from": "string",
      "valid_to": "string",
      "observations": 0,
      "magnitude": 0,
      "magnitude_unit": "string",
      "evidence": 0,
      "evidence_unit": "string",
      "confidence": "high"
    }
  ],
  "meta": {
    "next_cursor": "string",
    "count": 0,
    "total": 0,
    "subject": {
      "property1": "string",
      "property2": "string"
    },
    "as_of": "string",
    "as_of_by_rel": {
      "property1": "string",
      "property2": "string"
    },
    "excluded_shapes": [
      "event"
    ]
  }
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Que MEDIDAS existem no grafo, e em que escala cada uma

O catálogo, independente de objeto: todo `fact` que `getObjectFacts` pode devolver e `getObjectHistory` pode servir, com a régua e os tipos de objeto a que se aplica. Leia a coluna `unit` antes de comparar duas medidas. `ratio` é fração (0,08 é 8%) e `pct` é percentual (8,0 é 8%): `dy_12m` de ação é fração e `fii_dy_12m` de FII é percentual, então comparar os dois crus erra por 100×. **`dimension`, `scale` e `period` são a régua completa, e `period` é o eixo que `unit` não tem como dizer.** `dy_12m` cobre DOZE MESES, `fii_dividend_yield_month` cobre UM e `revenue_cagr_3y` é anualizado sobre TRÊS ANOS — três janelas que chegam na mesma resposta e que nenhuma unidade distingue. É a mesma armadilha do IPCA na `bcb_sgs:433` (o mês, ~0,4) contra a `bcb_sgs:13522` (doze meses, ~4,7). **O valor é servido AS-FILED e `scale` diz como lê-lo — ela não foi aplicada.** `portfolio_value_kbrl` é `currency` em `thousand`: os 508.272.696 da mediana são 508 BILHÕES de reais, não 508 milhões. E `scale` desmente sufixo de coluna quando a fonte mente: `fidc_acquired_impaired_pct` termina em `_pct` e vem em `unit` (fração, mediana 0,0204), enquanto `fidc_collateral_pct`, na MESMA tabela, é percentual de verdade. **`unit: native` não é uma escala — é a ausência de uma.** Diz que a escala não é do FATO, é de cada SÉRIE: `value` e `indicator_value` cobrem 431 séries macro em que a mesma medida sai em percentual numa e em fração decimal noutra — o IPCA acumulado em 12 meses é 4,44 na `bcb_sgs:13522` e 0,0444 em `macro:ipca_12m`. O catálogo não tem como resolver isso sem saber de QUE série se fala; quem resolve é `getObjectFacts` no objeto da série, que devolve a `unit` já resolvida e os eixos declarados em `axes`. Tratar `native` como unidade é o erro de 100× outra vez, agora sem nada na resposta para acusá-lo.

Atravessa uma relação a partir (ou em direção a) este objeto

Uma linha por AFIRMAÇÃO, com o outro lado já resolvido em nome e tipo — a mesma relação afirmada por duas fontes, ou interrompida e retomada, ocupa mais de uma linha. Para contar objetos, agrupe por `other_id`. `magnitude` é o tamanho que a fonte publicou (participação, peso no índice, valor de mercado) e **nulo não é zero**: significa que a fonte não publicou valor plausível. Prova documental é `getObjectEvidence`, não este campo. `valid_from`/`valid_to` delimitam o período — use `?at=` para o presente. **JÁ VEM ORDENADO POR `magnitude` DECRESCENTE, com nulo por último — então `limit=5` É o top-5.** Está escrito aqui porque a ausência custou caro: numa sondagem de 22/08/2026 um consumidor competente pediu "os cinco maiores donos da Vale", baixou as 341 arestas inteiras (160 mil caracteres) e ordenou por fora para chegar exatamente às cinco linhas que `limit=5` já devolveria. Capacidade que existe e não se anuncia é indistinguível de capacidade que não existe. No pior caso a diferença é entre uma chamada e o impossível: a ISA Energia tem **4.925** detentores, e a lista inteira não cabe em resposta nenhuma. O critério é o TAMANHO da aresta, não a data — e `magnitude` é o MÁXIMO do segmento, nunca o valor pontual, então isto ordena por "maior posição do período" e não por "maior posição hoje".