Measure a book's factor risk

Itoflow’s factor risk model splits a book’s risk into market, country, industry and style factors and each name’s own risk. It looks through ETFs to their holdings and reads the model as it stood on each past date, so you can see how a book’s risk changed over a year and why. What you’ll get: for each date, the book’s volatility, tracking error and beta against the benchmark, how much of its risk comes from factors and how much from single names, its factor exposures, the names that drive the most risk, and what the model couldn’t cover. When a fund holds derivatives, their value weights remain named gaps in the equity factor model. Coverage counts gains and losses by size: a +1% contract value and a −1% contract value leave 2% unmodelled, with 0% net value shown separately. A negative contract value is a loss; it does not establish a short exposure. Accounting balances, such as pending income, carry their stated value with a known zero return and do not count as unpriced holdings. For provider fund books, the rounding bound is the number of rows times half the finest stated weight unit in the book. A single finer row narrows the bound for all rows. The bound has a floor of one billionth and no cap: a book stated only to 0.1% can treat a 0.1% leftover as rounding. Owner and filing books keep the one-billionth bound.

Before you start

An Itoflow account. Risk measures need no extra account flag.
A book: one of your saved portfolios, or a list of up to 3,000 symbols and weights.

Quick start

Ask your AI assistant
In the Itoflow app
With the API

With Itoflow connected to your assistant, paste this into your assistant:

Use Itoflow to measure the factor risk of a book that holds 60% QQQ.US,
30% IWM.US and 10% cash, against SPY.US, at each month-end from November 2025
to September 2026. For each date, give total volatility, tracking error,
beta, the share of risk from factors and from single names, the five largest
factor exposures, the five names that drive the most risk, and anything the
model left out. Then tell me in which month the risk changed most, and why.
Wait for the measure to finish before you answer.

Open in Claude

Start this in Claude with the Itoflow plugin.

Open in ChatGPT

Start this in ChatGPT with the Itoflow plugin.

Using another client? Copy the prompt with the button on the code block.To measure your own book, replace the weights with the name of one of your saved portfolios.

You need an access token in ITOFLOW_ACCESS_TOKEN.

Start the measure

curl --fail-with-body --silent --show-error \
  'https://api.itoflow.ai/risk/measure' \
  --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "request_key": "7d2e4b18-5c3a-4f6e-9a21-0b8c7e5d3f42",
    "request": {
      "model": { "range": { "from": "2025-11-30", "to": "2026-09-30" } },
      "benchmark": "SPY.US",
      "top_names": 5,
      "books": [
        { "label": "growth tilt", "holdings": [
          { "symbol": "QQQ.US", "weight": 0.6 },
          { "symbol": "IWM.US", "weight": 0.3 },
          { "symbol": "CASH", "weight": 0.1 }
        ] }
      ]
    }
  }'

Use a new UUID as request_key for each measure. The response is 202 with a measure_id. To measure a saved portfolio, send { "label": "my book", "portfolio": { "portfolio_id": "PORTFOLIO_ID" } } as the book, with your portfolio’s ID.

Read it until it ends

curl --fail-with-body --silent --show-error \
  'https://api.itoflow.ai/risk/measure/MEASURE_ID' \
  --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN"

Replace MEASURE_ID with the measure_id. While status is running, read again every few seconds; progress counts the dates done. Eleven month-ends take a few minutes. A failed measure returns status: "failed" with a failure_code and a reason.

Read the answer

An ok answer has one entry in dates for each month-end, with its as_of date. For each date, books[0] holds:

Field	What it tells you
`risk.total_volatility`	Forecast annual volatility, as a decimal: 0.21 is 21%.
`risk.factor_share`, `risk.specific_share`	The percent of the book’s variance from factors and from single names. They add to 100.
`active.tracking_error`, `active.beta`	Against the benchmark.
`risk.exposures`	Exposure to each factor, in the order of the answer’s `factors` list.
`top_names`	The names with the largest share of the book’s risk.
`coverage`	The share of the book the model covers, and each line it left out, with a reason.

A null figure was not computed; it never means zero. A date the model has no publication for comes back as missing, with the nearest model dates on each side.

To split a change in a saved portfolio’s risk into what your trades did and what the market did, measure it twice in one request. See What moved risk.

What a result looks like

We ran the measure above on October 28, 2026. From November 2025 to September 2026:

Forecast volatility ran from 16% to 22%, highest at the end of December 2025.
Tracking error against SPY ran from 4.5% to 5.1%, and beta from 0.89 to 0.94.
Factors explained 89% to 94% of the book’s variance.
Looking through the two funds, the model covered 98% to 99% of the book. Each month it left out 49 to 108 small lines and listed up to 100 of them, each with a reason, such as fund cash with no stated currency.

Figures change as the model publishes new dates.

How it’s checked

The model is published, not fitted on demand. A daily build publishes dated snapshots, and each date reads the newest one on or before it. Agents and the API never refit it.
Gaps are named. A name the model doesn’t cover stays out at its weight, with its reason. It is never filled with a guess.
The model is scored against what happened. It was tested with the bias statistic and the 95% band MSCI defines for it, which is 0.82 to 1.18 over 59 month-ends. On the S&P MidCap 400 from September 2021 to July 2026, 107 of 116 test portfolios fell inside it. The volatility of optimized portfolios came within 4% of what followed, where a plain sample covariance was 17% to 26% too low. See How the model measures up.

Limits

1 to 10 books per measure, up to 3,000 lines each, and up to 60 dates.
A measure reads the names the model already covers. A risk run on the book adds names the model can score.
Bonds, futures and options held directly stay outside the model and are listed with their reason.
Looking through a fund needs its holdings dated on or before each date. Before the first holdings Itoflow has for a fund, the fund is listed as not covered.
Three risk runs or measures can run at once. A finished answer stays for 24 hours.

Next steps

Risk measure: every field and error.
Risk runs: today’s full report on one book, with attribution, scenarios and peer funds.
Monitor a portfolio: the same figures on a schedule, with a written report.

Get started

Platform

Use cases

Features

HTTP API

Troubleshooting

Endpoints