GET /v2/fundamentals/{symbol}/{dataset}

Company fundamentals for one symbol

fundamentals_getDataset

One fundamentals dataset for one company: valuation ratios, income statements, balance sheets, float, short interest or dividends. Rows are in data.results, newest first.

Path parameters

symbol string required: Symbol, e.g. AAPL
dataset string required: One of ratios, income, balance-sheet, float, short-interest or dividends. news is available in the ITMatrixHQ apps only (403 with an API key).

Query parameters

timeframe string: Statement period: quarterly|annual|trailing_twelve_months (default quarterly). Applies to income and balance-sheet.
limit integer · int32: Rows to return, newest first: 1 to 50 (default 8). Applies to income, balance-sheet and short-interest.

Details

dataset	what it holds	parameters
`ratios`	valuation and balance ratios (market cap, EV, P/E, P/B, EV/EBITDA, dividend yield and more) as of the latest date	none
`income`	income statements (revenue, net income, EPS and more)	`timeframe`, `limit`
`balance-sheet`	balance sheets (cash, liabilities, equity and more)	`timeframe`, `limit`
`float`	free float, as shares and percent	none
`short-interest`	short interest, average daily volume and days to cover, by settlement date	`limit`
`dividends`	declared cash dividends with ex, record and pay dates	none

income and balance-sheet serve one statement period per response (timeframe), so each response is a single series. The news dataset is available in the ITMatrixHQ apps only; with an API key it is 403 not_entitled_tier.

Units

Currency amounts are dollars: statement values in whole dollars, cash_amount per share.
Shares are counts; free_float_percent is percent (92.1 = 92.1%).
Ratios are unitless; dates are ISO YYYY-MM-DD.

Freshness

Fetched at request time. Statements update as companies report, ratios daily, and short-interest on the exchange settlement cycle.

Limits

At most 50 rows per response (limit, default 8). No other per-operation limit applies.

Empty results

A symbol with no data for a dataset returns 200 with an empty results list.

Example

http

GET /v2/fundamentals/AAPL/float

json

{
  "data": {
    "results": [
      {
        "ticker": "AAPL",
        "effective_date": "2026-05-14",
        "free_float": 13521179933,
        "free_float_percent": 92.1
      }
    ],
    "status": "OK"
  },
  "meta": { "dataset": "float", "symbol": "AAPL" }
}

Response

Prices are dollars, timestamps epoch milliseconds, strikes integer thousandths of a dollar; null means unknown. Units →

200application/json

The dataset in data: rows in data.results, newest first; meta.dataset, meta.symbol, and meta.timeframe / meta.limit where they applied

object

Errors

Every error is the JSON error envelope; branch on error.code.

Status	Meaning
400	`invalid_params` — unknown dataset / bad symbol / bad `timeframe` or `limit`
401	`unauthenticated`
403	`not_entitled_tier` — `news` requested with an API key (news is shown in the ITMatrixHQ apps only)
502	`internal` — the data source failed upstream
503	`internal` — the data source is not configured here

Request

curl -sS "https://api.itmatrixhq.com/v2/fundamentals/SPY/ratios" \
  -H "Authorization: Bearer $ITM_API_KEY"

import os
import httpx

response = httpx.get(
    "https://api.itmatrixhq.com/v2/fundamentals/SPY/ratios",
    headers={"Authorization": f"Bearer {os.environ['ITM_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

import os
import itmatrix as itm

with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
    result = client.fundamentals.get("SPY", "ratios")
    print(result.status, result.data)

const url = new URL("https://api.itmatrixhq.com/v2/fundamentals/SPY/ratios");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ITM_API_KEY}` },
});
console.log(response.status, await response.json());

import { ITMClient } from "@itmatrixhq/core";

const client = new ITMClient({ apiKey: process.env.ITM_API_KEY });
const result = await client.fundamentals.get("SPY", "ratios");
console.log(result.status, result.data);