# Cotações Históricas

> Acesse o histórico de cotações de ações, fundos imobiliários, BDRs, ETFs e outros ativos negociados na B3 (Ibovespa).

Acesse o histórico completo de cotações de ativos negociados na B3. Preços de abertura, fechamento, máxima, mínima e volume — tudo em um único endpoint!

<callout color="neutral" icon="tabler:key" to="/docs/guide/key">

Para acessar os dados da API é necessário utilizar uma chave de integração e um plano compatível.

</callout>

---

## Dados OHLCV

A API retorna dados no formato **OHLCV** (Open, High, Low, Close, Volume), padrão amplamente utilizado no mercado financeiro para análise técnica e construção de gráficos de candlestick:

<table>
<thead>
  <tr>
    <th>
      Campo
    </th>
    
    <th>
      Título
    </th>
    
    <th>
      Descrição
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        open
      </code>
    </td>
    
    <td>
      Abertura
    </td>
    
    <td>
      Preço do ativo no momento da abertura do período.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        high
      </code>
    </td>
    
    <td>
      Máxima
    </td>
    
    <td>
      Maior preço atingido pelo ativo durante o período.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        low
      </code>
    </td>
    
    <td>
      Mínima
    </td>
    
    <td>
      Menor preço atingido pelo ativo durante o período.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        close
      </code>
    </td>
    
    <td>
      Fechamento
    </td>
    
    <td>
      Preço do ativo no momento do fechamento do período.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        volume
      </code>
    </td>
    
    <td>
      Volume
    </td>
    
    <td>
      Quantidade total de ativos negociados no período.
    </td>
  </tr>
</tbody>
</table>

---

## Requisição

Informe o ticker no formato `{fonte}:{símbolo}`.

<endpoint endpoint="/v2/finance/history?tickers=B3:PETR4">



</endpoint>

<request-example endpoint="/v2/finance/history?tickers=B3:PETR4">



</request-example>

<stock-search>



</stock-search>

### Parâmetros

<field-group>
<field name="tickers" type="string" :required="true">

Ticker do ativo no formato `{fonte}:{símbolo}`. Para múltiplos ativos, separe por vírgula: `B3:PETR4,B3:VALE3`.

</field>

<field name="sample_by" type="string">

Controla a granularidade do histórico retornado. Opções disponíveis:

- `1m`: 1 minuto
- `5m`: 5 minutos
- `15m`: 15 minutos
- `30m`: 30 minutos
- `1h`: 1 hora
- `2h`: 2 horas
- `1d`: 1 dia
- `1M`: 1 mês

</field>

<field name="start_date" type="string">

Data inicial para filtrar o histórico (`yyyy-mm-dd`).

</field>

<field name="end_date" type="string">

Data final para filtrar o histórico (`yyyy-mm-dd`).

</field>

<field name="date" type="string">

Data específica para consultar cotações de um único dia (`yyyy-mm-dd`).

</field>

<field name="days_ago" type="number">

Número de dias atrás a partir de hoje. Use `0` para cotações do dia atual.

</field>
</field-group>

<callout color="warning" icon="tabler:alert-triangle">

Somente **um** tipo de filtro de data pode ser utilizado por requisição: intervalo (`start_date`/`end_date`), data específica (`date`) ou dias atrás (`days_ago`).

</callout>

---

## Resposta

<response-json endpoint="/v2/finance/history?tickers=B3:PETR4&days_ago=30">



</response-json>

### Campos

Os dados de cada ativo retornam no array `results`:

#### Ativo

<table>
<thead>
  <tr>
    <th>
      Campo
    </th>
    
    <th>
      Tipo
    </th>
    
    <th>
      Descrição
    </th>
    
    <th>
      Exemplo
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ticker
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Ticker completo no formato <code>
        {fonte}:{símbolo}
      </code>
      
      .
    </td>
    
    <td>
      B3:PETR4
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unit
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Unidade dos valores (<code>
        currency
      </code>
      
       para moeda).
    </td>
    
    <td>
      currency
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Moeda dos valores.
    </td>
    
    <td>
      BRL
    </td>
  </tr>
</tbody>
</table>

#### Cotações

Cada item do array `samples` representa uma cotação no período:

<table>
<thead>
  <tr>
    <th>
      Campo
    </th>
    
    <th>
      Tipo
    </th>
    
    <th>
      Descrição
    </th>
    
    <th>
      Exemplo
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        date
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Data e hora do período (ISO 8601).
    </td>
    
    <td>
      2026-01-16T00:00:00.000000Z
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        open
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          number
        </span>
      </code>
    </td>
    
    <td>
      Preço de abertura do período.
    </td>
    
    <td>
      31.95
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        close
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          number
        </span>
      </code>
    </td>
    
    <td>
      Preço de fechamento do período.
    </td>
    
    <td>
      32.04
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        high
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          number
        </span>
      </code>
    </td>
    
    <td>
      Preço máximo atingido no período.
    </td>
    
    <td>
      32.2
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        low
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          number
        </span>
      </code>
    </td>
    
    <td>
      Preço mínimo atingido no período.
    </td>
    
    <td>
      31.88
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        volume
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          number
        </span>
      </code>
    </td>
    
    <td>
      Volume total negociado no período.
    </td>
    
    <td>
      59717700.0
    </td>
  </tr>
</tbody>
</table>

<callout color="info" icon="tabler:info-circle">

**Entendendo os preços**: Os valores de `open`, `close`, `high` e `low` são expressos na moeda indicada pelo campo `currency`. Para ativos da B3, os valores são em Reais (BRL).

</callout>

#### Fonte

O objeto `source` contém informações sobre a bolsa de valores:

<table>
<thead>
  <tr>
    <th>
      Campo
    </th>
    
    <th>
      Tipo
    </th>
    
    <th>
      Descrição
    </th>
    
    <th>
      Exemplo
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        source.symbol
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Código da bolsa.
    </td>
    
    <td>
      B3
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source.name
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Nome da bolsa.
    </td>
    
    <td>
      B3
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source.full_name
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Nome completo da bolsa.
    </td>
    
    <td>
      B3 S.A. - Brasil, Bolsa, Balcão
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source.url
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Site oficial da bolsa.
    </td>
    
    <td>
      <a href="https://www.b3.com.br" rel="nofollow">
        https://www.b3.com.br
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source.location.timezone
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes one-light one-dark-pro one-dark-pro" language="ts-type" style="">
        <span class="s3iYH">
          string
        </span>
      </code>
    </td>
    
    <td>
      Fuso horário da bolsa.
    </td>
    
    <td>
      America/Sao_Paulo
    </td>
  </tr>
</tbody>
</table>