> ## 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. # Chat > Start research from your AI assistant over MCP and follow it to the end, read conversations and their results, download and share what a chat made, and run chats on your own ChatGPT subscription instead of Itoflow credits. > [!TIP] > > **The easiest way: ask your AI assistant.** With [Itoflow MCP](https://docs.itoflow.ai/mcp/install.md) connected to Claude or Codex, paste: > > ```text theme={null} > Use Itoflow to compare SPY and VTI diversification. Explain the method, include > sources, and wait for the research to finish before summarizing it. > ``` > > > [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%20compare%20SPY%20and%20VTI%20diversification.%20Explain%20the%20method%2C%20include%20sources%2C%20and%20wait%20for%20the%20research%20to%20finish%20before%20summarizing%20it.) > > > > 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%20compare%20SPY%20and%20VTI%20diversification.%20Explain%20the%20method%2C%20include%20sources%2C%20and%20wait%20for%20the%20research%20to%20finish%20before%20summarizing%20it.) > > > > Start this in ChatGPT with the Itoflow plugin. > > Using another client? Copy the prompt with the button on the code block. > > No tokens or code needed. You can also do this in the [Itoflow app](https://app.itoflow.ai/chat). The rest of this page covers the HTTP API. Chat is Itoflow's research agent. You ask a question; it writes and runs code against market and portfolio data, then answers with a dashboard of results and evidence. [Open Chat](https://app.itoflow.ai/chat) to try it. From your own tools you can: * **Start research** through [MCP](#run-research-through-mcp). The HTTP API doesn't start research turns. The old `POST /chat` endpoint and `siq` command-line tool are retired; use your Model Context Protocol connection for programmatic research. * **Read conversations** and their results with the HTTP API or MCP. * **Download files** a chat created. * **Share** a read-only copy of a chat. For research requests to start from, each with a published result, see [Use cases](https://docs.itoflow.ai/use-cases/overview.md). ## Choose reasoning depth In the app's composer, choose how much reasoning the agent spends on a turn: **Low**, **Medium**, **High** or **Extra High**. The choices depend on the model, and the selector shows the level the selected one runs at. If the model you switch to lacks your current level, the composer picks the nearest one. A change applies to the next run; a running or resumed task keeps the settings it started with. Your plan sets which [models](https://docs.itoflow.ai/features/billing.md#models-and-plans) you can choose. ## What a finished turn contains | Part | What it is | | - | - | | Dashboard | The final answer: text, tables, charts, formulas and method diagrams. It stands on its own. | | Progress updates | Short messages during the run, such as “I'm fetching price history.” They stay in the transcript. | | Working steps | What the agent did, one plain line per step: its reasoning, tool calls and delegate replies. While the agent works, the steps show open. When it finishes, they fold into one line above the answer, such as “Analyzed symbols, ran a command · 1 failed”. Open a step to see what the tool did: the command it ran and what it printed, the file it wrote, or the lines an edit changed. | | Independent review | A check of the agent's work at key steps, when the agent builds a workflow. | | Files | Code, data and reports the agent wrote, kept in the chat's private workspace. | The agent keeps working toward the result you asked for and shares progress updates along the way. Answering a clarification lets it resume that work. You can ask it to make reasonable research assumptions and state them. That instruction carries forward as it works; it still needs evidence for source facts and your authority for actions beyond the request. Send follow-up requests in the same chat to continue with its earlier results and saved files. Reopening the chat keeps its earlier conversation available; you do not need to paste earlier answers into a follow-up. After a connection failure, retry or ask the agent to continue from its saved work, then check the resulting dashboard and files. If the model provider can no longer find its saved response, Chat makes one recovery attempt using the stored conversation and completed tool results. It does not rerun those completed tools. Other failures still surface in the chat for retry or investigation. After an interrupted turn, Chat sends the saved conversation and completed tool results to the model, without relying on that turn's incomplete provider response. Long turns can recover across repeated restarts while their start or latest resume is within 90 minutes. Repeated crashes on the same software version can still stop recovery and show an error; check the saved result before retrying. The final dashboard contains the requested result and files, or explains a concrete blocker, what the agent tried, and what is needed to proceed. When one part is blocked, the agent continues other required work that remains possible; it does not ask permission to carry on with your existing request. The agent asks about preferences and constraints when they could materially change the work; optional refinements do not prevent a useful answer. If a core data or tool dependency prevents reliable analysis, it stops that analysis and explains the blocker. Peripheral data defects can be excluded when the remaining analysis stays reliable, with material coverage limits stated in the answer. If you ask for a status update or methodology alone, that can be the final answer. Material choices about your objective, risk, capital or permissions still need your answer before dependent research begins. Where user-context retention is enabled, long conversations keep the original request, later amendments and answered questions alongside compacted working context. This also applies when the agent resumes after a restart. If those user inputs exceed the supported context budget, the agent reports a context limit instead of silently removing requirements. Availability depends on the configured runtime. For a complex comparison, give the question, the data or portfolio to use, and any limits that matter, and ask for the method as well as the result. For example, paste this into your assistant: ```text theme={null} Use Itoflow to compare monthly rebalancing with a 5% drift-band rule for my largest portfolio after trading costs. Explain each rule with a small example, define realized tracking error, and chart the account against its benchmark. State which dates and holdings you used, and wait for the research to finish before summarizing it. ``` > [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%20compare%20monthly%20rebalancing%20with%20a%205%25%20drift-band%20rule%20for%20my%20largest%20portfolio%20after%20trading%20costs.%20Explain%20each%20rule%20with%20a%20small%20example%2C%20define%20realized%20tracking%20error%2C%20and%20chart%20the%20account%20against%20its%20benchmark.%20State%20which%20dates%20and%20holdings%20you%20used%2C%20and%20wait%20for%20the%20research%20to%20finish%20before%20summarizing%20it.) > > 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%20compare%20monthly%20rebalancing%20with%20a%205%25%20drift-band%20rule%20for%20my%20largest%20portfolio%20after%20trading%20costs.%20Explain%20each%20rule%20with%20a%20small%20example%2C%20define%20realized%20tracking%20error%2C%20and%20chart%20the%20account%20against%20its%20benchmark.%20State%20which%20dates%20and%20holdings%20you%20used%2C%20and%20wait%20for%20the%20research%20to%20finish%20before%20summarizing%20it.) > > Start this in ChatGPT with the Itoflow plugin. Using another client? Copy the prompt with the button on the code block. ## Shared agent memory Agents can remember information across your chats. Your Monitors and delegates share the same memory. Agents choose what to save and when to look it up. You can ask an agent to remember a preference, or to forget one when it changes. Memory is private to your account. Public shares cannot read or add to it. Deleting a chat keeps your memory; deleting your account deletes it. Do not ask agents to remember credentials. ## Read conversations | Task | Endpoint | | - | - | | List your chats | `GET /chats` | | Read a chat and its messages | `GET /chat/{id}` | | Read a chat's task count and status | `GET /chat/{id}/sync` | | Read a table a chat produced | `GET /dataframes/{chatId}/{dfName}` | | Delete a chat and its files | `DELETE /chat-runtime/chats/{chatId}` | `GET /chats` lists your ordinary Chats only. Each item includes nullable `resource_type`: `chat` for a classified Cloudflare Chat, or `null` for a compatible legacy API Chat. Monitor sessions and Cloudflare rows without a proven type stay out of the list. Pass `runtime=cloudflare` for current Chats only, or `runtime=api` for Chats from the previous chat system. `GET /chat/{id}` and its `/events` alias read ordinary Chat history; a Monitor session is read through its Monitor owner. The events alias returns saved history, not a live stream. Saved history updates as a turn progresses but can trail it. To follow a turn while it runs, use `agent.getTurn` through MCP. If saving a previous turn has not finished, a new research run can remain blocked even when its answer is visible. Wait and check the existing turn before submitting another request. Retrying a turn with the same `message_id` does not start the research again. > [!WARNING] > > Deleting a chat is permanent and removes its workspace files. Your connected integrations stay connected. If you lose the response, send the same delete again. ## Download files from a chat In the app, open **Files** in a chat to browse and download what the agent wrote. From code: 1. `GET /chat-runtime/chats/{chatId}/workspace` lists one folder. Pass `path` to open a subfolder, and `limit` and the returned `cursor` to page through a large folder. Paths are relative to the workspace root, such as `results/report.csv`. 2. `GET /chat-runtime/chats/{chatId}/downloads/workspace/{relativePath}` downloads one file. ```bash theme={null} curl --fail-with-body --silent --show-error --output report.csv \ 'https://api.itoflow.ai/chat-runtime/chats/3f2b8c1e-7a4d-4e5f-9b6a-2c8d1e0f4a7b/downloads/workspace/results/report.csv' \ --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" ``` * Listings leave out the agent's own runtime files and dependency caches. * Downloads can't resume part-way. A retry starts the file from the beginning. * Downloads don't wait for the agent's work. A file the agent is still writing can download part-written, so download results after the agent has finished with them. * A `409` means two other downloads or reads from this chat's workspace are in progress. Retry when one finishes. * Shared copies of a chat show that a file exists but never let readers download it. Through MCP, your assistant lists files with `workspace_list` and reads them, up to 32 MiB each, with the MCP `resources/read` method. Use the download endpoint for anything larger. ## Connected services and actions Chat can combine data from Itoflow and your [connected services](https://docs.itoflow.ai/features/integrations.md) with files in its workspace. Your permissions and required reviews and approvals still apply. * When a question concerns one of your connected services, Chat checks that service before searching the web. * If a connected service needs you to sign in again, Chat says so and names it. Reconnect it under **Integrations**. * Chat can find files that your earlier chats saved, such as a report or CSV file. It can only see your own chats. * Chat can start new chats and send messages to your other chats, then read their answers. Ask it, for example, to research two funds in two separate chats and compare the results. The chats it starts appear in your chat list, and you can open and continue them. Each chat has its own workspace, so Chat includes what the other chat needs in its message. The chat that receives a message sees which chat sent it and can reply. If a run fails after completing an action, that action is not undone. Check the current state before asking Chat to repeat a change. ## Run research through MCP [Connect your assistant](https://docs.itoflow.ai/mcp/install.md) first. Four methods, called through the MCP `execute` tool, run research: | Method | What it does | | - | - | | `agent.runTurn` | Sends a message to a new or existing chat and starts the research, or queues it while the chat is busy. | | `agent.getTurn` | Returns the turn's status, and its result when finished. | | `agent.cancelTurn` | Asks the turn to stop, or removes a message still waiting in the queue. | | `agent.listQueue` | Lists the messages waiting in the chat's queue. | ```javascript theme={null} const turn = await agent.runTurn({ chat_id: "chat-research-1", message_id: "message-research-1", message: "Compare SPY and VTI diversification.", model_key: "astra", }); ``` `runTurn` returns as soon as Itoflow accepts the turn. The research then runs for minutes; poll `getTurn` until it finishes, rather than sending the message again. Chat can assign part of a research task to a background analyst. The analyst sends its saved result back automatically, and the main agent can ask the same analyst follow-up questions with its earlier conversation intact. The main turn stays in progress while required results are pending. Keep polling the same `getTurn` until that turn returns its final result or a terminal error; clients cannot control internal delegates through the public API. Cancelling the main turn also stops its outstanding delegate work. The main agent and its background analysts share the chat's workspace. They can run commands in it at the same time, with no fixed limit. Running commands never block file reads or downloads. To retry after a lost response, send the same `message_id`, `message` and `model_key`; Itoflow treats it as the same turn. A new `message_id` starts a new turn. After reconnecting, use `agent.getTurn` with the same `chat_id` and `message_id` to read the saved result or failure. If the agent needs to ask you something mid-run, or wants your approval to create a portfolio, clients that can show forms display it. Other clients get the question, or a short summary of the portfolio, as text with a link to the Itoflow chat where you answer or approve. Text never approves a portfolio. A new message doesn't answer the question or the review: it waits in the queue until you do. A portfolio review lists the holdings with current prices, the cash and the amount to allocate. Choose **Create portfolio**, **Send changes to agent** (with a note) or **Reject import**. On **Create portfolio**, Itoflow creates the portfolio and the agent carries on with the result. If prices change before you choose, the form asks you to check again; if an earlier approval already created the portfolio, the form says so and won't create it twice. Declining or closing the form rejects the import; ask the agent if you want a new review. The review stays with the chat, so reloading the page shows the same rows. Later turns give the agent the review's counts, not every row, so a review of 3,000 holdings leaves room for the rest of the conversation. ### Queue messages while a turn runs Each chat has one queue, shared by the Itoflow app and MCP. While a turn runs, the agent waits for an answer, or messages are already waiting, `runTurn` adds your message to the queue and returns status `queued` with a `queue_position`: ```javascript theme={null} const queued = await agent.runTurn({ chat_id: "chat-research-1", message_id: "message-research-2", message: "Also compare their expense ratios.", }); // { accepted: true, status: "queued", queue_position: 1, ... } ``` Queued messages start one at a time, oldest first, when the current turn finishes. While the agent waits for an answer or a review, they keep waiting, with no time limit. * `agent.listQueue({ chat_id })` lists every waiting message, including ones queued in the app or by your other chats, with its `message_id`, `position`, a short `preview` and `paused_reason` (`awaiting_input` or `null`). * `getTurn` reports a waiting message as `queued` with its `queue_position`. * `cancelTurn` removes a waiting message before it starts, whichever side queued it. Once a message has started, `cancelTurn` stops it only if it came from MCP or from another chat; stop an app message in the app. A chat holds at most 10 waiting messages. ### Choose a model `model_key` accepts a fusion mode or a single model and saves it as the chat's choice. Later turns keep it unless you pass another. A new chat without a choice uses the plan's `default_mode` from `/pricing/model-access`. Fusion pins a main model and a separate Guardian; a single choice uses the same model for both. Retries keep both admitted routes. See [models and plans](https://docs.itoflow.ai/features/billing.md#models-and-plans). A paid choice on Free returns `403 model_subscription_required`; an unknown or disabled choice returns `409 model_unavailable`. On the Free plan, `/pricing/model-access` returns an `advisory` with `code: "free_plan_model_limitations"`, a `message` and an `upgrade_url`. MCP results that start research or create a monitor or strategy add the same notice as text. If you build a client, show it to the user once per conversation. Paid plans never receive it. ## Connect your own ChatGPT subscription Chat and monitor runs can use your ChatGPT subscription instead of Itoflow credits. Connect it in the app at [**Integrations → Codex (ChatGPT subscription)**](https://app.itoflow.ai/integrations#codex-subscription) (in the sidebar, or under **More** on mobile), or with these endpoints: ```mermaid theme={null} flowchart LR Start[Start connection] --> Approve[Approve the code with OpenAI] Approve --> Poll[Poll until connected] Poll --> Turn[Run research on your subscription] ``` | Endpoint | Returns | | - | - | | `POST /codex-subscription/start` | A code, the OpenAI approval URL, a polling `interval_seconds` and an expiry | | `POST /codex-subscription/poll` | `pending`, `connected`, `denied` or `expired` | | `GET /codex-subscription` | Whether the feature is on for you (`rollout`), and whether you're connected or have an approval in progress | | `DELETE /codex-subscription` | Disconnects | Itoflow turns this on for each account. Before you start, check that `GET /codex-subscription` returns `rollout: "enabled"`. If it's `disabled`, start returns `403 subscription_disabled`; ask [support@itoflow.ai](mailto:support@itoflow.ai) to turn it on. Open the approval URL, approve the code with OpenAI, then poll no faster than `interval_seconds`. If a previous disconnect is still being cleaned up, start, poll and disconnect return `503 disconnect_cleanup_pending`; try again shortly. **What it covers.** Chat and monitor runs, including their independent reviews, on a single OpenAI model choice. Fusion modes always use Itoflow keys for both agents and need plan access. A connected subscription gives you those models even on Itoflow's Free plan. It does not give you the Claude models: those need Pro or Max. Strategy runs still use Itoflow credits. **When the subscription can't be used.** If the connection needs signing in again or your ChatGPT plan refuses a request, for example because you reached its usage limit, the run continues on Itoflow credits at normal rates. The exception is a paid model that only your subscription gave you: that run stops and asks you to reconnect or choose another model, so you're never charged for a model your plan doesn't include. A very long turn can fail if its OpenAI access token expires part-way. See [billing](https://docs.itoflow.ai/features/billing.md#chatgpt-subscription-usage) for how this shows in your usage. **Security.** These endpoints never return OpenAI tokens. Itoflow keeps your refresh credential out of the agent's environment; the agent gets only a short-lived access token for its run. Disconnecting stops new runs from using the subscription straight away and asks OpenAI to revoke Itoflow's tokens. Deleting your Itoflow account removes the saved credential. ## More * [Sharing](https://docs.itoflow.ai/features/sharing.md): publish a read-only copy of a chat. * [Connect GitHub and MCP servers](https://docs.itoflow.ai/features/integrations.md): give Chat access to your repositories and other MCP servers. * [Chat endpoint reference](https://docs.itoflow.ai/api-reference/coverage.md#chat). * [What our quant-research agent actually does — and where it still needs a human](https://itoflow.ai/blog/what-our-quant-research-agent-actually-does): a worked research run, step by step. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.