> TickerLayer documentation for AI agents and LLMs, the Markdown version of https://tickerlayer.com/docs/rest/fundamentals
> REST base URL https://api.tickerlayer.com, API key in the `x-api-key` header. WebSocket wss://stream.tickerlayer.com?apiKey=YOUR_API_KEY.
> Any docs page reads as Markdown at its URL plus `.md`. Index: https://tickerlayer.com/llms.txt · Full API reference: https://tickerlayer.com/llms-full.txt

# Fundamentals REST endpoints

Company reference and share-structure data for US and EU stocks under /fundamentals: free float, shares outstanding, sector, ownership, short interest, and liquidity.

- **Auth:** x-api-key header
- **Base path:** /fundamentals
- **WebSocket:** REST only
- **Symbol format:** CC:SYMBOL (e.g. US:KO)

**Fundamentals is a data add-on:** $39/mo on Individual, $349/mo on Business, on its own or alongside your plan. [Get it on the add-ons page](https://tickerlayer.com/data-addons#fundamentals)

Needs the Fundamentals add-on, with or without live market data. Coverage is the US stock universe served by [Stocks](https://tickerlayer.com/docs/products/stocks), plus Germany (DE), Spain (ES) and France (FR); page through a market with `?market=DE`.

## How it works

- **Served from storage:** Our aggregation layer keeps the values current and TickerLayer storage serves them, so responses are fast and unaffected by upstream conditions.
- **Refresh:** Share-structure figures (float, shares outstanding, short interest, volumes) daily; profile fields (name, venue, sector, industry, country) monthly. `as_of` dates the share-structure figures and advances only on a real refresh.
- **One consistent set:** Share-structure figures are written together. If a restatement leaves one unavailable, the set keeps its previous values and `as_of`, so `float_ratio` and `short_float_ratio` never pair a new count with an old one.
- **No nulls:** A field without a reliable value is left out, never `null`. Ratios are computed from the counts in the same payload.
- **Depositary receipts:** Share count and float are each checked against the listing's market cap and traded price, in the units that trade (one receipt can stand for two, five or eight ordinary shares). A figure that fails is replaced by a named estimate, `shares_listed_est` or `free_float_est`, never both for one quantity. A receipt can therefore carry `free_float` without `shares_total`, and then no `float_ratio`. Use the reported fields for exact counts and the estimates for order of magnitude, as in low-float screens.

## Fundamentals for one symbol

**Endpoint:** `GET /fundamentals/stocks/{symbol}`

Returns the full fundamentals item for one market-qualified symbol. 404 when the symbol is unknown or has no fundamentals coverage yet (very fresh listings can lag a day).

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `symbol` | string | Yes | Market-qualified symbol (CC:SYMBOL, e.g. US:AAPL or DE:RHM). Fundamentals currently cover the US, DE, ES and FR markets. |

### Request

```bash
curl -sS "https://api.tickerlayer.com/fundamentals/stocks/US:KO" \
  -H "x-api-key: <YOUR_API_KEY>"
```

### Response

```json
{
  "symbol": "US:KO",
  "base_symbol": "KO",
  "market": "US",
  "company": "The Coca-Cola Company",
  "exchange": "NYSE",
  "mic": "XNYS",
  "country": "United States",
  "country_code": "US",
  "sector": "Consumer Defensive",
  "industry": "Beverages - Non-Alcoholic",
  "security_type": "Common Stock",
  "employees": 65900,
  "market_cap": 388735324105,
  "shares_total": 4303000000,
  "free_float": 3874015338,
  "float_ratio": 0.9003,
  "short_interest": 44821363,
  "short_float_ratio": 0.0116,
  "days_to_cover": 2.56,
  "insider_ownership": 0.099,
  "institutional_ownership": 0.686,
  "adv_10d": 12690023,
  "adv_90d": 15906204,
  "beta": 0.342,
  "as_of": "2026-08-20T11:56:49.392Z"
}
```

## Batch lookup

**Endpoint:** `GET /fundamentals/stocks?symbols=...`

Returns fundamentals for up to 100 symbols in one call. Symbols without coverage are listed under missing instead of appearing as empty items.

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `symbols` | string | Comma-separated market-qualified symbols, at most 100 per request. When present, the response is a batch lookup and market, cursor and limit are ignored. |

### Request

```bash
curl -sS "https://api.tickerlayer.com/fundamentals/stocks?symbols=US:KO,US:ZZZZ" \
  -H "x-api-key: <YOUR_API_KEY>"
```

### Response

```json
{
  "count": 1,
  "items": [
    { "symbol": "US:KO", "free_float": 3874015338, "shares_total": 4303000000, "...": "..." }
  ],
  "missing": ["US:ZZZZ"]
}
```

## Full universe, paged

**Endpoint:** `GET /fundamentals/stocks`

Pages through fundamentals for every covered symbol, ordered by symbol. Built for screeners: pull the whole universe in a handful of requests instead of one call per ticker, then filter locally (for example free_float below 10M).

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `market` | string | Market code to page through: US, DE, ES or FR. Defaults to US. |
| `cursor` | string | Resume marker from the previous page (next_cursor). Omit to start from the first symbol. |
| `limit` | integer | Rows per page, default 500, maximum 1000. |

### Request

```bash
curl -sS "https://api.tickerlayer.com/fundamentals/stocks?limit=1000" \
  -H "x-api-key: <YOUR_API_KEY>"
```

### Response

```json
{
  "market": "US",
  "count": 1000,
  "items": [ { "symbol": "US:A", "...": "..." } ],
  "next_cursor": "US:AVGO"
}
```

### Notes

Pass `next_cursor` from each response as `cursor` on the next request; the last page omits it. With `limit=1000` the full US universe is currently 8 requests.

## Field reference

Identity fields are always present; every other field is optional and left out when unknown. Ownership fields are fractions between 0 and 1.

| Parameter | Type | Description |
| --- | --- | --- |
| `symbol / base_symbol / market` | string | Identity of the listing, same convention as every other endpoint (US:AAPL, AAPL, US). |
| `company` | string | Issuer name. |
| `exchange / mic` | string | Listing venue and its MIC code (e.g. NYSE, XNYS). |
| `country / sector / industry` | string | Issuer origin country and classification. |
| `country_code` | string | ISO 3166-1 alpha-2 code of the issuer origin country, derived from country. Distinct from the market prefix, which is the listing venue: a depositary receipt can trade on market US with country_code CN. Omitted when the origin cannot be resolved to a code. |
| `security_type` | string | Instrument class, e.g. Common Stock. |
| `employees` | integer | Reported headcount. |
| `market_cap` | number | Market capitalization in the listing currency. Withheld together with shares_total when the pair fails the live-price cross-check on an ordinary listing. |
| `shares_total` | integer | Total shares outstanding, cross-checked against the market cap and the live traded price. On depositary receipts a count that contradicts the listing (reported on the ordinary-share base, or a stale vintage of it) is withheld and replaced by the estimates below. On ordinary listings a count and market cap that jointly contradict the live price by a wide margin (a stale pair, common on micro caps that reverse-split and re-dilute) are both withheld, with no substitute. |
| `free_float` | integer | Shares available for public trading (free float), in the units that trade on this listing. When the reported float runs up to 5% above shares_total, a sign that the two figures come from different reporting dates, it is rebuilt as shares_total less insider holdings. On a depositary receipt whose share count was withheld, the float is validated on its own against the listing and served when it holds up. Omitted when it cannot be reconciled with any share base. |
| `float_ratio` | number | free_float divided by shares_total, 0 to 1. Derived by our aggregation layer, always consistent with the counts in the same payload, and served only when both counts are. |
| `shares_listed_est` | integer | ESTIMATE of the listing-level share count (market cap over the live traded price). Served only for depositary receipts whose reported share count failed validation, so a symbol never carries both shares_total and shares_listed_est. An order-of-magnitude screening aid, not a reported figure. |
| `free_float_est` | integer | ESTIMATE of the listing-level float, served only for depositary receipts whose reported float failed validation, so a symbol never carries both free_float and free_float_est. When the float was reported on the ordinary-share base, its reported fraction is applied to the listing; otherwise the listing count is reduced by reported insider ownership, which does not see every controlling holder and so reads high. |
| `short_interest` | integer | Shares currently sold short. |
| `short_float_ratio` | number | short_interest divided by free_float. Derived, same guarantee as float_ratio. |
| `days_to_cover` | number | Short interest expressed in days of average trading volume. |
| `insider_ownership / institutional_ownership` | number | Fraction of shares held (0 to 1). |
| `adv_10d / adv_90d` | integer | Average daily share volume over 10 and 90 sessions. |
| `beta` | number | Beta versus the broad market. |
| `as_of` | string | ISO-8601 vintage of the share-structure figures in this item. It moves only when those numbers are actually refreshed, so it never overstates how current they are. Share structure refreshes daily; profile fields refresh monthly. |