> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bigdata_history_tearsheet

> Returns how a stock's closing price and short interest moved over time for up to five companies, as one CSV.

## Overview

The History Tearsheet returns a time series for up to five companies over a window of up to five years, built to be charted. Each row is one company on one date, with the figures you ask for: the closing price and the volume traded, then shares sold short and their value, the percent of free float sold short, days to cover, cost to borrow, shares available to borrow, and the short score.

Prices are end-of-day. The short interest figures are daily estimates, modelled from securities-lending data.

## When to Use

The History Tearsheet is ideal for:

* **Price against short interest:** How a stock's price moved beside its short interest, days to cover or borrow cost
* **Trends:** How short interest, borrow cost or lendable supply changed over a period
* **Comparisons:** The same figures for a handful of companies side by side, over the same dates
* **Point-in-time questions:** What the price or short interest was on a past date

## How It Works

1. **Call**: A call is made to `find_securities` (or `get_securities`) to resolve each company name or ticker
2. **Extract**: The `id` field is extracted from each result and used as an `rp_entity_id`
3. **Call**: A single call is made to `bigdata_history_tearsheet` with up to five `rp_entity_id` values, the figures you need and the window

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `rp_entity_ids` | array of strings | Yes | RavenPack entity IDs of 1 to 5 companies. Each ID is exactly 6 alphanumeric characters (for example `["D8442A", "86170D"]`). Must be obtained from `find_securities` or `get_securities`. |
| `metrics` | array of strings | No | The figures to return: `close`, `volume`, `short_interest`, `days_to_cover`, `cost_to_borrow`, `shares_available_to_borrow`, `short_score`. Omit to get `close` and `short_interest`. |
| `lookback` | string | No | How far back from `end_date` the window starts: `1M`, `3M`, `6M`, `1Y`, `2Y` or `5Y`. Default `1Y`. Ignored when `start_date` is given. |
| `start_date` | string | No | First day of the window (`YYYY-MM-DD`). Overrides `lookback`. |
| `end_date` | string | No | Last day of the window (`YYYY-MM-DD`). Defaults to today. |
| `frequency` | string | No | How often there is a row: `daily` (every trading day, the default), `weekly`, `monthly` or `quarterly`. |
| `days_to_cover_period` | string | No | The trailing window of average daily volume that days to cover divides by: `1W`, `2W`, `1M` or `3M`. Default `3M`. |

### Important Notes

* The window can span at most five years
* `weekly`, `monthly` and `quarterly` keep the last trading day of each period with that day's values. Weeks run Monday to Sunday, and a period the window cuts short, the current one included, still has a row
* Prices are in one currency, that of the first company given whose currency is known. A company that trades in another currency has empty price cells: ask for it in a separate call
* Prices and short interest can come from different listings of one company: SAP's prices come from its New York listing, in US dollars, and its short interest from Xetra. The response names both
* When your plan does not include the short interest data, the prices you asked for are returned and the response says which figures were left out. A request for short interest alone is refused
* A company the data does not cover for the figures asked for has no rows, and the response names it
* A daily series over a long window is long: for windows over three months, ask for a weekly or monthly frequency unless every trading day is needed

## Data Returned

The response is a short summary, a table of what each column holds, and the series as CSV. The CSV starts with `date` and `rp_entity_id`, then one column per figure, in this order whatever order the metrics were asked in:

| Metric | Columns | Description |
| - | - | - |
| `close` | `close` | Last traded price of the day, in the currency named on the column |
| `volume` | `volume` | Shares traded that day |
| `short_interest` | `shares_short` | Shares sold short and not yet bought back |
| | `shares_short_value_usd` | Market value of the shares sold short, in US dollars |
| | `percent_of_free_float` | Shares sold short as a percentage of the shares that trade freely |
| `days_to_cover` | `days_to_cover` | Shares sold short divided by the average daily volume over `days_to_cover_period` |
| `cost_to_borrow` | `cost_to_borrow` | Yearly fee for borrowing the shares, in percent, averaged over all open loans |
| | `cost_to_borrow_new_loans` | The same yearly fee, in percent, on loans opened that day |
| `shares_available_to_borrow` | `shares_available_to_borrow` | Shares still available to borrow, as a percentage of the shares sold short |
| | `shares_available_to_borrow_count` | Shares still available to borrow, not counting shares already on loan |
| `short_score` | `short_score` | A ranking of short-selling pressure across all stocks, from 0 to 100 |

Rows are grouped by company, in the order the IDs were given, and each company's dates run oldest first. An empty cell means no value that day: short interest can have a row on a market holiday, when there is no price.

The structured content carries the same CSV with each company's name and a description of each column. `mapping` names, for each company, the symbol its prices come from (`price_symbol`) and the listing its short interest comes from (`short_interest_listing`), each present when its figures are asked for. `prices_left_out` names any company left out of prices for its currency, and `withheld_metrics` names any figure your plan does not include.

### Example

A weekly series of the default figures, the closing price and short interest, for Spotify (`86170D`) and Apple (`D8442A`) over September 2026. Both trade in US dollars:

```csv theme={null}
date,rp_entity_id,close,shares_short,shares_short_value_usd,percent_of_free_float
2026-09-04,86170D,542.43,4888360,2651593120,3.112122
2026-09-11,86170D,525.75,6144135,3230279134,3.911605
2026-09-18,86170D,509.45,6122921,3119322263,3.898053
2026-09-25,86170D,510.01,4627767,2360207610,2.946028
2026-09-30,86170D,487.38,4531763,2208690423,2.884912
2026-09-04,D8442A,319.97,120429922,38533962230,0.82661
2026-09-11,D8442A,332.27,137835167,45798490948,0.946077
2026-09-18,D8442A,336.13,136081289,45741003785,0.93404
2026-09-25,D8442A,341.07,129002708,43998953714,0.885453
2026-09-30,D8442A,333.02,127133892,42338128731,0.872626
```

## Practical Tips

### Charting Price Against Short Interest

Plot the figures you compare in one chart, with short interest on a second axis, to see how they move together. To compare companies, plot each one's close as a percentage change from its first day, so their prices share one scale. When measuring how two series relate, correlate their day-to-day changes rather than their levels: two series that both trend look correlated on levels even when they are not.

### Reading Short Interest

Compare `percent_of_free_float` across companies rather than `shares_short`: a large company can have many more shares sold short and still be far less heavily shorted. `days_to_cover` says how long short sellers would need to buy their shares back at normal volume, so a rising value with flat short interest means trading volume is falling.

### Reading Borrow Cost and Supply

A rising `cost_to_borrow` together with falling `shares_available_to_borrow` means borrowing is getting tighter. `cost_to_borrow_new_loans` covers only loans opened that day, so it shows what borrowing costs now, while `cost_to_borrow` averages every loan still open.

### Choosing a Frequency

Use `daily` for windows of a few weeks or when the exact day matters, and `weekly` or `monthly` for longer trends. A coarser frequency keeps the response short without changing the values: each row is a real trading day's figures, not an average.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.