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

# Measure a book's factor risk

> Measure a portfolio's factor risk against a benchmark with Itoflow's factor risk model: volatility, tracking error, beta, factor exposures and the names that drive risk, at one date or month by month, looking through ETFs to their holdings and naming every gap.

Itoflow's [factor risk model](https://docs.itoflow.ai/platform/quant-engine.md#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.

```mermaid theme={null}
flowchart LR
  Book[Your book or a list of weights] --> Model[Factor risk model at each date]
  Benchmark[Benchmark holdings] --> Model
  Model --> Answer[Risk, exposures and gaps by date]
```

## 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

> [tab] Ask your AI assistant
>
> With [Itoflow connected to your assistant](https://docs.itoflow.ai/mcp/install.md), paste this into your assistant:
>
> ```text theme={null}
> 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.
> ```
>
> > [card] [Open in Claude](https://claude.ai/new?q=Use%20the%20Itoflow%20plugin%20\(https%3A%2F%2Fgithub.com%2Fitoflow%2Fskills\)%20for%20this.%20If%20it%20isn't%20installed%20yet%2C%20first%20tell%20me%20how%20to%20install%20it%20and%20sign%20in%20to%20Itoflow%2C%20and%20wait%20until%20I%20confirm.%20Then%3A%0A%0AUse%20Itoflow%20to%20measure%20the%20factor%20risk%20of%20a%20book%20that%20holds%2060%25%20QQQ.US%2C%2030%25%20IWM.US%20and%2010%25%20cash%2C%20against%20SPY.US%2C%20at%20each%20month-end%20from%20November%202025%20to%20September%202026.%20For%20each%20date%2C%20give%20total%20volatility%2C%20tracking%20error%2C%20beta%2C%20the%20share%20of%20risk%20from%20factors%20and%20from%20single%20names%2C%20the%20five%20largest%20factor%20exposures%2C%20the%20five%20names%20that%20drive%20the%20most%20risk%2C%20and%20anything%20the%20model%20left%20out.%20Then%20tell%20me%20in%20which%20month%20the%20risk%20changed%20most%2C%20and%20why.%20Wait%20for%20the%20measure%20to%20finish%20before%20you%20answer.)
> >
> > Start this in Claude with the Itoflow plugin.
>
> > [card] [Open in ChatGPT](https://chatgpt.com/?q=Use%20the%20Itoflow%20plugin%20\(https%3A%2F%2Fgithub.com%2Fitoflow%2Fskills\)%20for%20this.%20If%20it%20isn't%20installed%20yet%2C%20first%20tell%20me%20how%20to%20install%20it%20and%20sign%20in%20to%20Itoflow%2C%20and%20wait%20until%20I%20confirm.%20Then%3A%0A%0AUse%20Itoflow%20to%20measure%20the%20factor%20risk%20of%20a%20book%20that%20holds%2060%25%20QQQ.US%2C%2030%25%20IWM.US%20and%2010%25%20cash%2C%20against%20SPY.US%2C%20at%20each%20month-end%20from%20November%202025%20to%20September%202026.%20For%20each%20date%2C%20give%20total%20volatility%2C%20tracking%20error%2C%20beta%2C%20the%20share%20of%20risk%20from%20factors%20and%20from%20single%20names%2C%20the%20five%20largest%20factor%20exposures%2C%20the%20five%20names%20that%20drive%20the%20most%20risk%2C%20and%20anything%20the%20model%20left%20out.%20Then%20tell%20me%20in%20which%20month%20the%20risk%20changed%20most%2C%20and%20why.%20Wait%20for%20the%20measure%20to%20finish%20before%20you%20answer.)
> >
> > 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.

> [tab] In the Itoflow app
>
> 1. Open [Chat](https://app.itoflow.ai/chat).
> 2. Name the book, such as one of your saved portfolios, the benchmark, and the dates.
> 3. Ask for volatility, tracking error, beta, factor exposures and the names that drive risk. The answer shows the engine's figures with the agent's notes.
>
> To get the same figures on a schedule, [monitor the portfolio](https://docs.itoflow.ai/use-cases/portfolio-monitoring.md).

> [tab] With the API
>
> You need an [access token](https://docs.itoflow.ai/authentication.md#get-an-access-token) in `ITOFLOW_ACCESS_TOKEN`.
>
> **1. Start the measure**
>
> ```bash theme={null}
> 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.
>
> **2. Read it until it ends**
>
> ```bash theme={null}
> 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`.
>
> **3. 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](https://docs.itoflow.ai/api-reference/risk-measure.md#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](https://docs.itoflow.ai/platform/quant-engine.md#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](https://docs.itoflow.ai/api-reference/risk-runs.md) 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](https://docs.itoflow.ai/api-reference/risk-measure.md): every field and error.
* [Risk runs](https://docs.itoflow.ai/api-reference/risk-runs.md): today's full report on one book, with attribution, scenarios and peer funds.
* [Monitor a portfolio](https://docs.itoflow.ai/use-cases/portfolio-monitoring.md): the same figures on a schedule, with a written report.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.