Building an AI agent? Start with /llms.txt for the full site index.
Market Structure & Reference
Realized decile-spread returns per factor: for each (factor_name, date, horizon), the top-decile return, bottom-decile return, and their spread — a statistical FACT computed from the factor library, with universe/decile counts and the return basis. No good/bad label. Not a forecast, not a recommendation.
GET /v2/datasets/factor-returnsThis dataset is in build and not yet queryable via the API. The coverage and honest limitations below are the real database state; it moves off "Building" once serving lands (targeted 8/1).
| Field | Type | Description |
|---|---|---|
horizon | enum | 1m / … |
decile_spread_return | ratio | top−bottom (identity) |
top_decile_return | ratio | |
bottom_decile_return | ratio | |
n_universe | int | |
return_basis | text | |
forward_end_date | date | realized horizon end |
390 rows, 2026-05-08..2026-05-28 (prototype window, same as factor_library). decile_spread_return = top_decile_return − bottom_decile_return (identity, recomputable). return_basis + formula_version carried. Short window → not a long-run factor premium claim.
A real response from this endpoint. Rows are returned under "data", and provenance is carried in the shape shown below — it is not identical across datasets, so read this page's rather than assuming another's.
{ "dataset_id": "factor-returns", "row_count": 3, "data": [ { "factor_name": "dividend_yield_z", "trade_date": "2026-05-08", "horizon": "1m", "decile_spread_return": -0.02889607, "top_decile_return": 0.00038349, "bottom_decile_return": 0.02927956, "n_universe": 645, "return_basis": "adj_close_hfq", "forward_end_date": "2026-06-08" }, { "factor_name": "dividend_yield_z", "trade_date": "2026-05-11", "horizon": "1m", "decile_spread_return": -0.02100226, "top_decile_return": 0.01405615, "bottom_decile_return": 0.03505842, "n_universe": 646, "return_basis": "adj_close_hfq", "forward_end_date": "2026-06-09" }, { "factor_name": "dividend_yield_z", "trade_date": "2026-05-12", "horizon": "1m", "decile_spread_return": 0.03417932, "top_decile_return": 0.02408166, "bottom_decile_return": -0.01009766, "n_universe": 802, "return_basis": "adj_close_hfq", "forward_end_date": "2026-06-10" } ]}Captured from the live API on 2026-07-20.
curl "https://api.twmarketdata.com/v2/datasets/factor-returns?symbol=2330" \ -H "X-API-Key: sk_live_..."| Parameter | Required | Type | Description |
|---|---|---|---|
symbol | Yes | string | Ticker, e.g. 2330. |
start_date | No | string (YYYY-MM-DD) | Start of the query range. |
end_date | No | string (YYYY-MM-DD) | End of the query range. |
limit | No | integer | Maximum rows to return. |
A first call:
import requests resp = requests.get( "https://api.twmarketdata.com/v2/datasets/factor-returns", params={"symbol": "2330"}, headers={"X-API-Key": "sk_live_..."},)resp.raise_for_status()print(resp.json()["data"])With a date-range filter:
import requests # The full verified example — the same call with every supported filter set.resp = requests.get( "https://api.twmarketdata.com/v2/datasets/factor-returns", params={"symbol": "2330"}, headers={"X-API-Key": "sk_live_..."},)resp.raise_for_status()for row in resp.json()["data"]: print(row)This endpoint is GET /v2/datasets/factor-returns. The full machine-readable schema (parameters, security, response envelope) lives in the OpenAPI spec.