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

# Market data & benchmarks

> Daily prices and market caps per security, 465 index and commodity benchmark series, and FINRA short interest.

Four routes cover the price layer: a company's daily prices and market caps, the benchmark registry, benchmark daily series, and semi-monthly short interest.

All four require the **Professional** plan (or Fund) and cost **1 credit** per call. Responses use the standard envelope with `{ data, next_cursor, coverage }` — see [Pagination](/concepts/pagination) and [Errors](/concepts/errors).

<Warning>
  **Read the unit before the number, in both halves.** A company with several listings returns one row per symbol per date, each in its own currency, nothing converted — no single row is "the" price. And twelve commodities quote in US **cents** (currency `USX`): corn at 508.5 is \$5.085 a bushel. Benchmark rows carry `close_major` / `currency_major` with the figure converted to the major unit — read those.
</Warning>

## GET /v1/companies/\{company\_id}/market-data

One security's daily series, newest first. The path accepts a `cmp_` id, ticker, CIK or ISIN; an unrecognised-but-plausible symbol is still tried as a symbol, since the series is keyed on the listing.

**Plan:** Professional and above · **Credits:** 1 per call

<ParamField path="company_id" type="string" required>
  Canonical `cmp_` id, ticker, CIK or ISIN.
</ParamField>

<ParamField query="series" type="string" default="prices">
  Which daily series: `prices` or `market_cap`. They are different tables with different row shapes.
</ParamField>

<ParamField query="date_gte" type="string">
  Start date, `YYYY-MM-DD`.
</ParamField>

<ParamField query="date_lte" type="string">
  End date, `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  `next_cursor` from the previous page, passed back verbatim.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Rows per page, 1–1000.
</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/AAPL/market-data?series=prices&date_gte=2026-08-01&limit=5" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "symbol": "AAPL",
      "company_id": "cmp_000123",
      "date": "2026-08-26",
      "currency": "USD",
      "open": 231.5,
      "high": 234.2,
      "low": 230.9,
      "close": 233.7,
      "adj_close": 233.7,
      "volume": 51234567
    }
  ],
  "next_cursor": "MjAyNi0wOC0yNg",
  "coverage": {
    "available_from": "2025-07-14",
    "available_to": null,
    "update_frequency": "daily",
    "history_status": "one_year_from_2025_07_14"
  }
}
```

The `market_cap` series rows carry `symbol`, `company_id`, `date`, `currency`, and `market_cap`.

<Warning>
  History starts **2025-07-14** — about one year. A request for an older range returns nothing, and that is a fact about the dataset, not the security. One year cannot support a multi-year backtest or a 5-year return; the benchmark series below is the only long-run price history here.
</Warning>

## GET /v1/benchmarks

The benchmark registry — which indices and commodities exist and how they are spelled. 425 indices and 40 commodities.

**Plan:** Professional and above · **Credits:** 1 per call

<ParamField query="q" type="string">
  Symbol or a fragment of the name: `GCUSD`, `gold`, `Nikkei`. Results are ranked so the headline instrument leads — "S\&P 500" returns `^GSPC` first, not a derivative index.
</ParamField>

<ParamField query="kind" type="string">
  `index` or `commodity`.
</ParamField>

<ParamField query="limit" type="integer">
  Max rows, 1–500.
</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/benchmarks?q=nikkei" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "symbol": "^N225",
      "kind": "index",
      "name": "Nikkei 225",
      "exchange": "OSE",
      "currency": "JPY"
    }
  ],
  "coverage": {
    "available_from": "2015-01-01",
    "available_to": null,
    "update_frequency": "daily",
    "history_status": "complete"
  }
}
```

<Warning>
  Benchmark symbols are the vendor's spellings and cannot be guessed: the S\&P 500 is `^GSPC`, gold is `GCUSD`, 37 indices have no `^` at all, and `000001.SS` is the Shanghai **Composite**, which looks exactly like a Shanghai listing. Search the registry rather than constructing a symbol.
</Warning>

## GET /v1/benchmarks/\{symbol}

One benchmark's daily series, newest first. History reaches **2015-01-01** — ten years, where the company price series holds one.

**Plan:** Professional and above · **Credits:** 1 per call

<ParamField path="symbol" type="string" required>
  Benchmark symbol from the registry, e.g. `^GSPC`, `GCUSD`.
</ParamField>

<ParamField query="date_gte" type="string">
  Start date, `YYYY-MM-DD`.
</ParamField>

<ParamField query="date_lte" type="string">
  End date, `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  `next_cursor` from the previous page, passed back verbatim.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Rows per page, 1–1000.
</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/benchmarks/GCUSD?date_gte=2026-08-01&limit=5" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

Each row carries `symbol`, `kind`, `name`, `date`, `open`, `high`, `low`, `close`, `volume`, `currency`, and the unit-safe pair `close_major` / `currency_major` — equal to `close` / `currency` for everything that does not quote in cents.

<Note>
  Benchmark rows exist on weekends and are not dirty data: Saudi and Egyptian markets trade Sunday, CBOT grains run a Sunday-evening session, and a few calculated indices republish Friday's value on Saturday.
</Note>

<Note>
  A company identifier does not work on the benchmark routes and vice versa. Benchmarks carry no `company_id` on purpose — an index is not an issuer — so there is no join between the two halves beyond the date.
</Note>

## GET /v1/companies/\{company\_id}/short-interest

FINRA short interest for a US-listed security: shares sold short, the change since the prior settlement, and days to cover. Settled twice a month (mid-month and month-end), published about eight days later. History from **2017-12-29**.

**Plan:** Professional and above · **Credits:** 1 per call

<ParamField path="company_id" type="string" required>
  Canonical `cmp_` id, ticker, CIK or ISIN.
</ParamField>

<ParamField query="date_gte" type="string">
  Earliest settlement date, `YYYY-MM-DD`.
</ParamField>

<ParamField query="date_lte" type="string">
  Latest settlement date, `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  `next_cursor` from the previous page, passed back verbatim.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Rows per page, 1–1000.
</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/GME/short-interest?limit=3" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

Each row carries `company_id`, `ticker`, `issue_name`, `category`, `market_class_code`, `settlement_date`, `current_short_position`, `previous_short_position`, `change_previous`, `change_percent`, `average_daily_volume`, `days_to_cover`, `float_shares`, `float_as_of`, `short_percent_float`, `short_percent_outstanding`, `revision_flag`, and `stock_split_flag`, newest settlement first.

<Note>
  The newest row is never today: publication lags settlement by roughly eight days.
</Note>

<Note>
  `short_percent_float` is computed against a share-count source that only covers recent settlements, so it is null across the older history while the reported position beside it is complete. Null there means no share count, not no shorts.
</Note>