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

# Monitor a portfolio

> Set up a monitor that checks your portfolio against a benchmark, peer funds and your tracking-error, sector and single-name limits, and writes a report on a schedule.

A portfolio monitor watches your portfolio the way an oversight committee would: what it holds, how it differs from its benchmark and peers, how easily it could be sold down, and whether it stays inside the limits you set. Itoflow's risk engine computes the figures; the agent explains what changed and why.

**What you'll get:** a scheduled report on the portfolio, with numbered findings, its tracking error and active weights against the benchmark, comparisons with peers, and liquidity at different portfolio sizes.

Use any portfolio you keep in Itoflow: one you imported, a paper portfolio, or one connected to your broker. This guide compares it with the S\&P 500 and a minimum-volatility peer fund. Swap in the benchmark, peers and limits that fit your portfolio.

```mermaid theme={null}
flowchart LR
  Portfolio[Your portfolio] --> Monitor[Fund-oversight monitor]
  Monitor --> Engine[Risk engine figures]
  Engine --> Report[Scheduled report]
```

## Before you start

* An Itoflow account.
* A portfolio in Itoflow that no strategy runs. If you don't have one yet, [import your holdings](https://docs.itoflow.ai/features/portfolios.md#import-holdings) or [connect a broker](https://docs.itoflow.ai/features/brokers.md). The assistant and the app can also help you build one along the way.

## Quick start

> [tab] Ask your AI assistant
>
> With [Itoflow connected to Codex or Claude](https://docs.itoflow.ai/mcp/install.md), paste this into your assistant:
>
> ```text theme={null}
> Use Itoflow to set up oversight of one of my portfolios. List my portfolios and
> ask me which one to monitor. If I don't have one yet, help me import my
> holdings and show me the full import draft before saving it. Then propose a
> fund-oversight monitor on that portfolio: benchmark S&P 500 (index GSPC.INDX,
> basket SPY.US), peer fund USMV.US, a 4% tracking-error budget against the
> benchmark, sector limits of 15 points and single-name limits of 6 points either
> side of the benchmark, and a weekly report every Monday at 08:00
> America/New_York. If the S&P 500 is a poor fit for what the portfolio holds,
> suggest a better benchmark first. Show me the monitor before creating it. Once
> I approve, create it, enable it, run the first report, and summarize its
> findings.
> ```
>
> > [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%20set%20up%20oversight%20of%20one%20of%20my%20portfolios.%20List%20my%20portfolios%20and%20ask%20me%20which%20one%20to%20monitor.%20If%20I%20don't%20have%20one%20yet%2C%20help%20me%20import%20my%20holdings%20and%20show%20me%20the%20full%20import%20draft%20before%20saving%20it.%20Then%20propose%20a%20fund-oversight%20monitor%20on%20that%20portfolio%3A%20benchmark%20S%26P%20500%20\(index%20GSPC.INDX%2C%20basket%20SPY.US\)%2C%20peer%20fund%20USMV.US%2C%20a%204%25%20tracking-error%20budget%20against%20the%20benchmark%2C%20sector%20limits%20of%2015%20points%20and%20single-name%20limits%20of%206%20points%20either%20side%20of%20the%20benchmark%2C%20and%20a%20weekly%20report%20every%20Monday%20at%2008%3A00%20America%2FNew_York.%20If%20the%20S%26P%20500%20is%20a%20poor%20fit%20for%20what%20the%20portfolio%20holds%2C%20suggest%20a%20better%20benchmark%20first.%20Show%20me%20the%20monitor%20before%20creating%20it.%20Once%20I%20approve%2C%20create%20it%2C%20enable%20it%2C%20run%20the%20first%20report%2C%20and%20summarize%20its%20findings.)
> >
> > 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%20set%20up%20oversight%20of%20one%20of%20my%20portfolios.%20List%20my%20portfolios%20and%20ask%20me%20which%20one%20to%20monitor.%20If%20I%20don't%20have%20one%20yet%2C%20help%20me%20import%20my%20holdings%20and%20show%20me%20the%20full%20import%20draft%20before%20saving%20it.%20Then%20propose%20a%20fund-oversight%20monitor%20on%20that%20portfolio%3A%20benchmark%20S%26P%20500%20\(index%20GSPC.INDX%2C%20basket%20SPY.US\)%2C%20peer%20fund%20USMV.US%2C%20a%204%25%20tracking-error%20budget%20against%20the%20benchmark%2C%20sector%20limits%20of%2015%20points%20and%20single-name%20limits%20of%206%20points%20either%20side%20of%20the%20benchmark%2C%20and%20a%20weekly%20report%20every%20Monday%20at%2008%3A00%20America%2FNew_York.%20If%20the%20S%26P%20500%20is%20a%20poor%20fit%20for%20what%20the%20portfolio%20holds%2C%20suggest%20a%20better%20benchmark%20first.%20Show%20me%20the%20monitor%20before%20creating%20it.%20Once%20I%20approve%2C%20create%20it%2C%20enable%20it%2C%20run%20the%20first%20report%2C%20and%20summarize%20its%20findings.)
> >
> > Start this in ChatGPT with the Itoflow plugin.
>
> Using another client? Copy the prompt with the button on the code block.

> [tab] In the Itoflow app
>
> 1. Open [New monitor](https://app.itoflow.ai/watchlists/new) and choose **Use an existing portfolio**, then pick your portfolio. If you don't have one, choose **Search symbols** or **Upload a holdings file** and Itoflow helps you build it.
> 2. Under **What should this monitor track?**, set a benchmark, such as `SPY.US`, any peer funds, and your limits, such as a 4% tracking-error band. Select **Continue to chat**. The chat opens with your message filled in. If you chose a holdings file, attach it in the chat box. Then send the message.
> 3. If you started without a saved portfolio, check the portfolio the agent prepares and confirm it.
> 4. The agent asks for anything it still needs, then saves the monitor paused and starts its first report. It tells you what it saved. Ask for any changes in the same chat.
> 5. On the monitor's page, select **Edit** and set a schedule, such as weekly on Monday at 08:00.
> 6. Turn on **Agent reports** so the schedule runs. Without a schedule, this sets a daily 08:00 report in your time zone.
> 7. The first report appears on the monitor's page when it finishes.
>
> Check **Report history** for each scheduled date. If a previous date is still
> running, the new date shows a failure that names it, while the older report
> continues. Select a failed run to read the reason. An outage may delay the
> history update, but schedule history keeps each due date. A run still open at
> its next scheduled time becomes a visible failure. Pausing keeps dates already
> due and stops future dates; resuming skips the paused gap. A waiting report uses
> the configuration current when it starts and keeps its original local date.

> [tab] With the API
>
> You need an [access token](https://docs.itoflow.ai/authentication.md#get-an-access-token) in `ITOFLOW_ACCESS_TOKEN`.
>
> **1. Find your portfolio**
>
> ```bash theme={null}
> curl --fail-with-body --silent --show-error \
>   'https://api.itoflow.ai/portfolios' \
>   --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" |
> jq '.portfolios[] | { portfolio_id, name, linked_strategy }'
> ```
>
> Pick a portfolio whose `linked_strategy` is `null` and note its `portfolio_id`. To create one from your holdings first, see [Import holdings](https://docs.itoflow.ai/features/portfolios.md#import-holdings).
>
> **2. Create the monitor**
>
> ```bash theme={null}
> curl --fail-with-body --silent --show-error \
>   'https://api.itoflow.ai/watchlists' \
>   --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "name": "Portfolio oversight",
>     "mandate": "Lead with material changes against the benchmark and explain what caused them.",
>     "profile": "fund_oversight",
>     "profile_config": {
>       "subject": { "name": "My portfolio", "portfolio_id": "PORTFOLIO_ID" },
>       "comparators": {
>         "benchmark": { "name": "S&P 500", "index_symbol": "GSPC.INDX", "basket_symbol": "SPY.US" },
>         "peer_funds": [{ "name": "Minimum volatility peer", "symbol": "USMV.US" }]
>       },
>       "thresholds": {
>         "relative_weight": { "sector": 15, "single_name": 6 },
>         "tracking_error_budget": 4
>       }
>     },
>     "recurrence": { "kind": "weekly", "weekdays": ["monday"], "local_time": "08:00", "timezone": "America/New_York" }
>   }'
> ```
>
> Replace `PORTFOLIO_ID` with the ID from the previous step. The monitor starts paused. See [fund-oversight monitors](https://docs.itoflow.ai/features/monitors.md#create-a-fund-oversight-monitor) for every limit and its unit.
>
> **3. Enable it and run the first report**
>
> `POST /watchlists/{id}/control` with `{"action": "enable"}` arms the weekly schedule. To get a report now, `POST /watchlists/{id}/reports/run`.
>
> **4. Read the report**
>
> `GET /watchlists/{id}/active-execution` shows the run in progress. When it finishes, `GET /watchlists/{id}/reports/latest` returns the report.

## Limits

* A strategy can't run the portfolio you monitor.
* Reports use the portfolio's current positions, so you can't run a report for an earlier date.
* Risk figures measure a fund held beside other holdings through its dated holdings at the line's signed weight. Holdings lists, concentration and liquidity keep the fund line.
* Each peer fund needs published holdings; a symbol with price history alone isn't enough.
* A plain index with no basket fund is compared by returns only.

## Next steps

* [Monitors](https://docs.itoflow.ai/features/monitors.md): every limit, warning level and report field.
* [Get a daily news brief](https://docs.itoflow.ai/use-cases/daily-news-brief.md): add news on the portfolio's holdings.


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