> ## 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. # Market data and risk > Read quotes and prices, per-symbol analytics against a benchmark, FX rates and a factor-risk covariance matrix, and search stored news and SEC filings by meaning or by company, including news that never names the company. > [!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 get the factor-risk covariance for AAPL.US, MSFT.US and SPY.US as > of 2026-06-30, and explain which pair moves most together. > ``` > > > [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%20get%20the%20factor-risk%20covariance%20for%20AAPL.US%2C%20MSFT.US%20and%20SPY.US%20as%20of%202026-06-30%2C%20and%20explain%20which%20pair%20moves%20most%20together.) > > > > 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%20get%20the%20factor-risk%20covariance%20for%20AAPL.US%2C%20MSFT.US%20and%20SPY.US%20as%20of%202026-06-30%2C%20and%20explain%20which%20pair%20moves%20most%20together.) > > > > 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. Start by turning a ticker or company name into an Itoflow symbol such as `AAPL.US`; see [Find and resolve symbols](https://docs.itoflow.ai/guides/symbols.md). Every endpoint that takes an instrument expects that form; FX, benchmark, leaderboard and cache-status reads take no symbol. ```mermaid theme={null} flowchart LR Query[Ticker or company] --> Resolve[Itoflow symbol] Resolve --> Quotes[Quotes and symbol cards] Resolve --> Analytics[Symbol analytics] Resolve --> Risk[Factor risk] Resolve --> News[Stored news] ``` ## Quotes and prices | Endpoint | Returns | | - | - | | `POST /symbols/quotes` | Recent quotes for up to 60 symbols, sent as `{"symbols": ["AAPL.US", "MSFT.US"]}` | | `GET /symbols/baseline` | Summary cards for the `symbols` you pass | | `GET /symbols/cache-status` | How fresh the stored quotes are | | `GET /benchmarks` | Benchmark performance for comparisons | | `GET /fx-rates` | Current exchange rates | | `GET /fx-rate` | One exchange rate | | `GET /leaderboard` | Anonymous strategy rankings, by `period` | `POST /symbols/quotes` returns only quotes Itoflow already holds and leaves out symbols it has none for. A missing quote doesn't mean the symbol is invalid. For supported listing markets, the price reader uses FMP intraday bars. A latest price comes from the newest completed one-minute bar available, with no extra 15-minute delay imposed by Itoflow. The provider's feed may itself be delayed, and a closed market may retain an earlier session's price. The bar keeps its actual source time; a successful fetch does not make an older price current. The reader accepts bars within a 14-day lookup window. The last minute bar can differ from the official daily closing price, including after the session ends. Use daily history when you need the daily close. Intraday history retains its requested interval and price and volume basis. Each listing still needs a verified provider link; missing coverage remains unavailable rather than switching providers. Paper trades accept a positive converted price without checking whether its source time belongs to the current session. A market whose feed has not published today's bars can therefore fill a paper trade at an earlier session's price. The trade records when it executes, which can be later than the price observation. Check source time separately when deciding whether an observation is suitable for a current-session trade. For symbol cards, a name with no linked price history is unresolved; other names can still return cards. Provider timeouts and connection or upstream faults follow the [read rule](#symbol-analytics). If a second attempt fails without an answer from the same provider since it began, the request fails. Overlapping final attempts can instead return partial data. Eligible public source replies can be shared across callers until their refresh deadline, even if the original calculation failed. A cache hit does not certify identity, coverage or point-in-time eligibility. Historical reads preserve the provider's row order and include announced future events within the requested window. Each historical reader applies its own cutoff and validates the records it consumes. A quote's `price` is in US dollars; `native_price` and `currency` give the price in the currency it trades in. Holdings and trades keep their own currency, and your display-currency setting doesn't change it. Convert with the FX endpoints when you need to. Daily history and corporate actions select a provider by the listing's market and the requested data. A listing needs a verified link to the provider's exact exchange, securities identifier, share class and quoted currency. Missing or conflicting identity can leave that listing unavailable; an exchange appearing in a provider directory does not prove full coverage. Pence (`GBp`/`GBX`), rand cents (`ZAc`/`ZAC`) and agorot (`ILA`) retain their units in native daily prices and dividends. Share volume counts shares and never scales with currency. Symbol discovery uses the same units: a pence listing returns `GBX`, rather than `GBP`. The exchange directory includes the markets served by these daily routes and the four held German floors. In markets that require ISIN evidence, Python and TypeScript discovery check the exact provider profile when a search row lacks it, whether you search one market or all markets. The profile must confirm the same listing, exchange and quoted currency before the candidate or its currency can be used. Missing or conflicting evidence leaves the candidate out. An older link missing that evidence cannot supply daily prices. Frankfurt (`F`), Dusseldorf (`DU`), Munich (`MU`) and Stuttgart (`STU`) keep EODHD daily history and actions because FMP serves a different price stream on those floors. FMP can restate earlier raw closes after rights issues, spin-offs and demergers; its raw history may differ from prices recorded before those events. ```mermaid theme={null} flowchart LR Listing[Verified listing] --> Route[Market and requested data] Route --> History[Daily history and actions] ``` The leaderboard never shows whose strategy is whose; you can see only which rows are your own. ## Historical index research For a historical index in Chat, specify the listing market, selection dates, implementation lag, liquidity rule, weighting, costs and required files. For a thematic index, Chat builds a versioned, cited research universe, then applies dated listing, liquidity and capitalization rules at each rebalance. The report states the universe's research date, discovery sources and hindsight limits. Current classifications can inform that research universe. Reconstructing how thematic membership changed over time is a separate method to request explicitly; a current description cannot establish past membership. SEC filing availability uses a stated proxy: the later of acceptance or 06:00 New York time on its official filing date. This excludes late submissions before their assigned day. Exact website-publication times are unavailable; the report states this timing limit. The US calendar uses NYSE session dates as an aggregate market convention. This does not assign NYSE identity to a Nasdaq or other US listing; primary listing and quoted-security identity need their own dated evidence. The historical dataset reader's `price_session_coverage()` checks retained bars against the publication's declared market calendar. It reports missing, extra and duplicate sessions with source pins, separately from identity and action qualification. Optional `start` and `end` dates restrict the check to an acquired window. Calendar failures propagate; the check never fills missing bars or upgrades the bundle's other coverage. Calendar functions take platform market codes such as `US`, rather than a provider's venue labels. For a verified same-security ticker change, historical acquisition queries each FMP ticker within its effective date range. Raw bars retain one security ID, the actual provider symbol and source pins. Matching identity and a unique dated transition are required; an ambiguous change never fills an ended price series. Check session coverage and corporate actions separately. `prepare_historical_equity_dataset` reads a bundle from the shared market-data cache and builds it in the Chat sandbox when the cache has none. A large request takes minutes. Request smaller date windows with their decision cutoffs, retain each bundle and reconcile overlapping observations. The function makes no automatic retries or substitutions. Strict historical calculations need validated datasets with dated identity, prices, quoted-class shares and corporate-action terms. The library's source adapters own acquisition and validation; the agent must not fill missing financial records with web search or hand-written observations. Missing data can prevent an exact reconstruction. When the request allows estimates, use a disclosed proxy with a dated source and test whether reasonable alternatives change selection, weights or conclusions. Keep estimated results distinct from observed facts. Statement readers fill a blank reporting currency only when statement rows available by that row's own availability date agree on one whole-unit currency. The read cutoff also applies. Later filings cannot supply or veto that currency. A section-wide currency counts only through its dated rows. Subdivision units such as pence can block agreement but never fill a blank. A stated currency keeps its unit. Listing and price currencies do not fill statement gaps. Ordinary shares outstanding and EPS weighted-average shares are different inputs. Retain measurement time, actual publication time, accession and source. An ADR price needs shares on that receipt's quoted-unit basis. Current ticker metadata cannot establish a retired security's identity, and a named subset does not establish a complete historical market universe. A successful source request or a diagnostic coverage report does not establish a completed index. Research qualifies each consumed input and can combine supported readers with checked original documents. An incomplete bundle does not make every input unavailable; unresolved facts still need evidence before dependent calculations. Historical capitalization can use the latest actual share count published by each cutoff, carried forward on the price's physical share basis. Disclose its measurement date, publication date, age and known intervening capital changes. This estimates capitalization; it does not assert that the exact cutoff-day count was public. Verified price history for the same identified security establishes that it traded by that date, without a separate IPO-completion announcement. Price history alone supplies neither share counts nor past business eligibility. The dated report reader selects original annual/interim or admission reports known at each declared decision time and returns readable text with publication times and source pins. It keeps retained amendments separately and removes attributes and explicitly hidden markup. The underlying originals remain available for source checks and event research. This aids business research; it does not establish thematic eligibility or primary-listing history. An eligible original interim remains readable when no earlier annual or admission report exists. Its interim role does not imply complete business history; assess whether its actual content supports the research decision. Reports also retain unambiguous registered symbol, security title and exchange facts from the same issuer and filing context in `registered_securities`. Publication times and original source hashes remain attached. These records support dated listing research; they do not certify a global primary venue, continuous listing history or a binding to today's identifier. Incomplete or conflicting registration facts remain unqualified. The library reads original SEC reports and their declared share-fact attachments. Receipt conversion terms must appear in the report or its linked securities exhibit. It retains separate sources for the share count and quoted-unit terms; rounded share aggregates cannot establish a receipt ratio. An inline cover count without a class dimension can qualify only when its own explicit declaration identifies the registered class and agrees with the fact's date, issuer and share units. Nearby class names cannot qualify an aggregate. This applies to common-stock titles with or without a lettered class; a cover's navigation link alone does not make the count a financial-statement fact. Historical registered ticker/class counts remain available as separate source observations. They require dated legal continuity evidence before research can assign them to a current listing; a shared issuer alone does not prove that link. Requests for documents and actions also retain original material-event filings and their declared event exhibits, with source hashes and actual publication times. Research can derive exact action terms from this governed corpus and retain the supporting evidence. A price factor or an empty action table cannot substitute for that evidence. For a newly listed company with no annual report public at the decision cutoff, the library can retain its final IPO prospectus or latest registration as dated listing-admission research. Offering and pro-forma quantities remain research evidence until actual issuance and quoted-class units have been established. The research agent calls `prepare_historical_equity_dataset` with one US listed company's share, such as `AAPL.US`, and historical dates and decision cutoffs; funds are out of scope. FMP's profile fixes the listing's identity, the library acquires fixed-source evidence, and the agent receives a verified, versioned bundle. Bundles stay in the shared cache for 72 hours under a daily write limit; once that limit is reached, a new bundle stays in the calling process only. The function accepts no financial observations or source URLs. A publication's coverage describes its observed records; estimated research must declare any additional proxy convention. For several listings, acquisition can reuse a fresh market directory while retaining its original source hashes and retrieval times. Each listing still needs its own identity, price, report and event evidence. Directory reuse does not establish historical eligibility. The universe table also retains bounded current FMP descriptions, classifications and listing flags as `current_profile_observation` rows. Their `current_discovery_only` scope, retrieval time and source hash identify them as discovery metadata; they do not prove past business or primary-listing status. The same table retains paged FMP sector/industry/venue leads as `current_screen_observation` rows alongside separate retired-directory leads. Discovery does not filter by current market cap or issuer domicile. The dated report and share-count readers validate the requested cutoff: a missing early report or share fact does not hide usable later observations. An unavailable requested cutoff still fails, and full-history coverage remains unchanged. `overview()` shows retained input counts and coverage without dumping source documents. Exact `request_id` and `bundle_id` properties pin later reads. The `discovery_leads()`, `raw_price_observations()` and `action_observations()` views retain source fields and explicitly remain observations. A failed convenience reader does not discard that acquired data. Research must still qualify dated identity, currency, expected sessions and physical action terms before using it in calculations; these views never promote incomplete coverage or fill a missing price tape. Historical index workflows can declare the acquisition or reader helper as the source of their price, volume and fundamental inputs. The source declaration identifies the route; the calculation must still qualify its consumed records. A listing's identity comes only from FMP's exact profile for its ticker. Caller-provided identity overrides are refused. When ISIN discovery returns several US quotations, an exact canonical ticker still needs matching profile identity, currency and venue; a conflicting profile cannot redirect the request to another quotation. For public fund filings, an equity row in USD that has no usable listing keeps its stated weight and its match failure: historical and retired US leads from its ISIN, derived CUSIP or ticker are matched by listing currency and price. A row that already names a USD listing keeps that listing unchanged. The match failure remains part of the fund-book evidence rather than being treated as a zero weight. A quarterly filing book with an unread line is not stored; the next run reads that quarter again. Name-based recovery requires a readable share class or series designator to match the candidate's exactly. An explicit `class`, `cls` or `cl` followed by an unreadable token (`CLASS AA`, `CL.AA`) leaves the row unresolved even when a candidate's price matches. `series` and `ser` are ordinary words unless a readable designator follows (`Series A`, `Series 2`). A class word at the end of a name (`Share Class`) states no designator. For a retired quote with a missing price tail, a request can include the `aliases` family. The library qualifies a forward ticker change only when dated provider transitions and exact security, issuer, currency and venue evidence agree. Alias rows retain effective dates and source identities. Use those epochs with the normal price reader and raw units; a pure rename changes neither shares nor cash. Ambiguous chains remain unresolved. Qualified aliases alone do not establish historical primary status, legal action terms or complete price-session coverage. The normal dividend reader preserves declaration, record and payment dates when supplied by the provider. An absent payment date does not imply payment on the ex-date. For source reconciliation, requesting actions retains FMP's original dividend observations in the bundle's universe table, including declaration, record and payment dates when supplied. Qualify amounts against the exact quoted units and currency, and keep receivables until the sourced payment date. A corporate-action price factor does not always change the parent's shares. Spin-offs require separate child entitlements at the issuer's stated ratio. Historical portfolios should retain source evidence and reconcile physical shares, cash, dividends, trades and fees. An index capped at each daily close does not establish full UCITS or intraday compliance. For capitalization weighting, the Chat library's `proportional_weights` helper preserves the actual positive market-cap amounts and supports proportional cap redistribution. Score-ranking weights follow a different rule. Physical trades, fees and daily compliance still require a portfolio replay. These are Chat research capabilities, not a historical market-cap HTTP endpoint. The quote and analytics routes below retain their stated contracts. ## Symbol analytics `GET /symbols/analytics` returns the analytics a research monitor computes before it writes a report, for any 1 to 12 symbols. You don't need a monitor, and Itoflow saves nothing to one. Symbol analytics is rolling out: until it is turned on for your account, this route returns `404`. ```bash theme={null} curl --fail-with-body --silent --show-error \ 'https://api.itoflow.ai/symbols/analytics?symbols=AAPL.US,MSFT.US,NVDA.US' \ --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" ``` | Query parameter | Meaning | | - | - | | `symbols` | 1 to 12 comma-separated symbols; a repeated symbol counts once. A ticker without an exchange, such as `AAPL`, means its US listing. A symbol may use letters, digits and `.` `-` `^` `=` `_` `&`; anything else returns `400 invalid_symbols`. | | Response field | Meaning | | - | - | | `as_of` | The date of the latest close used, as `YYYY-MM-DD` | | `computed_at` | When Itoflow computed the analytics | | `cache.hit` | `true` when the result is one Itoflow computed earlier and kept | | `cache.ttl_seconds` | How long Itoflow keeps the result: 600, or 60 when some symbols or data sources failed, so a retry soon gets fresh figures | | `snapshot.symbols` | Each symbol's returns, volatility, beta against `snapshot.benchmark` (`SPY.US`), 52-week range, signal z-scores, fundamentals, valuation, analyst views and sector percentiles. A symbol without price data has only `error`, such as `no_price_data`. | | `snapshot.watchlist` | The symbols taken together: an equal-weight index against the benchmark, sector mix, market regime, correlation and highlights | | `snapshot.computed_for_symbols` | The symbols that had price data | | `snapshot.data_receipt` | Which inputs Itoflow fetched and which failed | A figure Itoflow can't compute is left out or `null`, never zero. Itoflow keeps each result for `cache.ttl_seconds`, so asking again within that time returns the same `computed_at`. It keeps no error, so the next request computes again. Analyst views and forward valuation depend on the symbol's data provider. US listings and listings on LSE, XETRA, PA, AS, SW, TO, AU, OL, KO, KQ, SHE, ST, CO, BR, MC, WAR and HE take point fundamentals, financial statements and earnings from FMP. It states trailing figures and no analyst forecasts. For those symbols `analyst.covered` is `false` with a `note`, and the forward P/E, PEG ratio and target price are `null`. Itoflow never fills them with a trailing figure or zero. Market-wide fundamentals snapshots and fund holdings keep their existing routes. SHG, TSX Venture (`V`), London IOB (`IL`) and Frankfurt (`F`) retain EODHD fundamentals. A listing without a verified provider binding has no point fundamentals; Itoflow reports them as not known. Non-US statement rows use results-release dates when valid filing dates are absent; a period end alone never establishes when the market could have known a figure. When a symbol's price history times out, loses its connection or meets an upstream error that waiting may clear, Itoflow waits 5 seconds and reads again. If it still fails, it waits 30 seconds and reads once more. An answer ends the retries. If the last read still fails this way, Itoflow leaves the symbol without volume figures only if the same provider answered another request after that last read began. `snapshot.data_receipt` names the unread symbol; other symbols keep their figures. A failed last read without an answered request in that interval fails the whole read. If several last reads overlap the provider's last answer before it stops responding, they can all be left out and the read can return the rest. Rate limits, spent quotas, refused keys, unsupported routes, unavailable snapshots, unknown faults and calendar faults still fail the read. Daily factor fits and month-end fills fail before storing results when read faults leave out more than 1% of the distinct names asked for prices or metadata. Exactly 1% is allowed. Observed gaps, such as no coverage or no currency rate, do not count. A failed fit keeps the last publication. Factor-model publications and return receipts use Monday through Friday. Daily fits and month-end fills remove weekend price bars before computing returns, including listings without exchange metadata. A weekend session's move enters the return of the next weekday its venue trades. Historical publications use the latest weekday price on or before the requested cutoff; live publications use their latest weekday price. | Status | `error` | Meaning | | - | - | - | | `400` | `invalid_symbols` | You passed no symbols or more than 12. | | `422` | `symbol_analytics_unavailable` | None of the symbols has price data. `unresolved` lists them. | | `503` | `symbol_analytics_compute_failed` | Itoflow couldn't compute the analytics. Try again later. | A token with limited scopes, such as one issued to an AI agent, needs `symbols.read`. ## Factor-risk covariance For a portfolio's factor card and factor-risk read, an open holding with no current price is left out, with no value or weight; the rest use the net asset value without it, with a `missing_price_symbols` warning. `POST /factor-risk/covariance` returns a covariance matrix for a set of symbols from Itoflow's factor risk model, as it stood on a past date. It uses the model snapshot from that date, so you can use it in backtests. Check `provenance.classification_inputs`: when it is `current_static`, the sector and country labels are today's rather than that date's. Country factors group companies by the provider's stated country: EODHD gives its listing venue's country; FMP gives its head-office country. The separate head-office country fact drives the [oversight country split](https://docs.itoflow.ai/features/monitors.md). Adding that fact does not change any country-factor assignment. Funds have no loadings of their own, so this endpoint refuses funds with status `422`. For a book that holds funds, use [risk measure](https://docs.itoflow.ai/api-reference/risk-measure.md) (`POST /risk/measure`); it reads through their stored holdings. Live model price inputs use completed venue sessions. A venue that is closed for the day uses its last completed trading bar; an open session waits for its close and closing auction. Historical requests retain their stated cutoff. ```bash theme={null} curl --fail-with-body --silent --show-error \ 'https://api.itoflow.ai/factor-risk/covariance' \ --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{"as_of": "2026-06-30", "symbols": ["AAPL.US", "MSFT.US", "JPM.US"]}' ``` | Request field | Meaning | | - | - | | `as_of` | The date, as `YYYY-MM-DD`. Itoflow uses the latest model snapshot on or before it. | | `symbols` | Up to 1,000 distinct symbols | | `model_version` | Optional. Pin a model version; defaults to the current one. | | Response field | Meaning | | - | - | | `symbols`, `covariance` | The matrix, with rows and columns in the order of `symbols` | | `snapshot_as_of` | The snapshot date actually used | | `base_currency` | The currency the returns are measured in | | `return_convention` | `simple_daily` or `log_daily` returns | | `annualization_factor` | Trading days per year, for scaling: 252 | | `warnings`, `symbol_warnings` | Data-quality notes, overall and per symbol | | `provenance` | How the snapshot was built, including whether the matrix needed a small correction to stay valid (`psd_repaired`) | Before a fit reads returns, it drops zero-volume flat bars before a listing's first trade. This check affects new fits and later reads; it does not rewrite stored publications. Daily venue limits are checked as described below. Keep `snapshot_as_of` and `base_currency` with any numbers you store. Don't compare matrices from different dates or currencies. To learn how the model works, read [How we built a cross-asset factor risk model](https://itoflow.ai/blog/factor-risk-models-for-agentic-portfolios) and [how it compares with Barra](https://itoflow.ai/blog/factor-risk-model-vs-institutional-providers). ## Search stored news `GET /news` searches the public news and SEC filings that Itoflow has stored. It returns headlines, links and ratings, not article text. Each call works in one of four ways: * **By query.** With `q`, Itoflow selects possible matches by similarity, then a model judges whether those candidates bear on your words, by meaning and in any language. Items without a vector also reach the judge. This can find items that never name the subject. Each row is a story: other matches that repeat it fold into it, and `repeats` counts them. Stories come most important first. The model judges the most important candidates first and stops once the rest could not change the rows, so a search can judge far fewer items than it selected. * **By company.** With `symbols` or `monitor_id`, a model first rates the window's news for each company, counting news about its rivals, customers, suppliers, inputs and market. The call then returns the rated items, newest first. * **As a list.** With none of these, the call lists the stored items, newest first, and judges nothing. * **As stories.** With `order=stories` or `order=stories_newest` and none of `q`, `symbols` or `monitor_id`, the call lists stories and judges nothing. Repeats fold into one row per story, shown by the story's highest-impact article in the window. With `stories`, stories come by the UTC day of their first report, newest first, then by impact, then by `published_at`. With `stories_newest`, the same stories come by the shown row's `published_at` descending, then `id` descending. A story keeps the day of its first report, even when that report was stored before the window. With either story order, `hide_commentary=true` drops stories whose shown row has `is_event_p < 0.5`, before the call applies `limit`; a row at exactly 0.5 stays. A model call takes time, so judging stops after about 25 seconds. `coverage.complete` says whether the reply is final: for companies, the model judged every selected candidate in the window; for a query, more judging could not change the rows. It does not mean every stored item reached the judge. Ratings for companies are kept, so a company search that stopped early goes further when you call again with the same input. A query search keeps nothing; call again with fewer `days`. | Query parameter | Meaning | | - | - | | `q` | What the news should be about, in plain words, up to 200 characters. Can't be combined with `symbols` or `monitor_id`. | | `symbols` | Up to 20 comma-separated symbols in `TICKER.EXCHANGE` form. Companies are rated in the order you give. | | `monitor_id` | Search the current holdings of one of your monitors, heaviest first, with each holding's weight. With `symbols` as well, only the holdings named. | | `days` | How many days back to search, by when Itoflow stored the item. From 1 to 90, default 7. With `q`, from 1 to 3, default 1. | | `order` | `newest` (default), `stories`, or `stories_newest`. Neither story order can be combined with `q`, `symbols` or `monitor_id`. | | `hide_commentary` | Boolean, default `false`. With `true`, keep only stories whose shown row has `is_event_p >= 0.5`, before `limit`. Requires `order=stories` or `order=stories_newest`. | | `country` | Only with a story order: keep the stories with an article in the window that names this country, as an ISO 3166-1 alpha-2 code such as `JP`. | | `sector` | Only with a story order: keep the stories whose shown article has this sector, one of the `sector` values below. Combines with `country`. | | `min_level` | `minor` (default), `notable`, or `material`. With `symbols` or `monitor_id`, it applies to the company rating; otherwise to the item's `impact`. With either story order, it applies to each article before repeats fold. | | `limit` | Rows to return, from 1 to 50. Default 20. With `q` or either story order, it counts stories. The response has no next page. | ```bash theme={null} curl --fail-with-body --silent --show-error \ 'https://api.itoflow.ai/news?q=chip%20export%20rules&days=2' \ --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" ``` A `200` response, trimmed to one story without its `url` and `publisher`: ```json theme={null} { "items": [ { "id": "8d0f3a52-6c1b-4e9a-b7d4-1f2e3a4b5c6d", "source": "gdelt_translingual", "title": "Den Haag scherpt exportregels voor chipmachines aan", "title_en": "The Hague tightens export rules for chip machines", "language": "nl", "published_at": "2026-09-25T13:45:00.000Z", "sec_form": null, "level": "notable", "impact": 2.1, "is_event_p": 0.93, "repeat_of": null, "symbols": [], "countries": ["NL", "US", "CN"], "sector": "information_technology", "match_p": 0.97, "repeats": 4 } ], "coverage": { "sources": ["gdelt", "gdelt_translingual", "sec_edgar"], "searched_from": "2026-09-23T14:00:00.000Z", "complete": true, "stored_through": "2026-09-25T14:00:00.000Z", "judged_from": "2026-09-23T14:00:00.000Z", "judged_items": 812 }, "unknown_symbols": [] } ``` | Field | Meaning | | - | - | | `source`, `language`, `title_en`, `is_event_p`, `repeat_of` | As in the [monitor news feed](https://docs.itoflow.ai/features/monitors.md#news-feed) | | `sec_form` | The SEC form, such as `8-K`, for a filing; `null` for news | | `impact` | How much the item could move the companies or markets it concerns, from 0 (none) to 3 (material) | | `level` | With `symbols` or `monitor_id`, the level of the top company rating; otherwise the level of `impact`. `material` from 2.5, `notable` from 1.5, `minor` from 1. | | `symbols` | The item's ratings for the symbols you asked for, or with `monitor_id` for that monitor's holdings, highest `materiality` first. Empty when you pass neither. | | `weight` | With `monitor_id`, the holding's current share of the portfolio's net assets, a short counted by its size; `null` for research monitors, for a portfolio worth nothing or less, and for a portfolio whose value is not known because an open holding lacks a usable price, currency or exchange rate. Always `null` without `monitor_id`. | | `countries` | Up to three countries the article names, as ISO 3166-1 alpha-2 codes, most named first. Empty for SEC filings and for articles that name no country. | | `sector` | The sector the article is about: one of the 11 GICS sectors (`energy`, `materials`, `industrials`, `consumer_discretionary`, `consumer_staples`, `health_care`, `financials`, `information_technology`, `communication_services`, `utilities`, `real_estate`), or `economy` for the economy as a whole. `null` when the article has not been sorted. | | `match_p` | With `q`, the model's chance that the item bears on your query; `null` otherwise. Stories rank by `match_p` × `impact` ÷ 3, newest first on ties. | | `repeats` | With `q`, how many other matches repeat this story. With `order=stories` or `order=stories_newest`, how many other articles of the story are in the window. 0 otherwise. | | `story_day` | Only with `order=stories` or `order=stories_newest`: the UTC day of the story's first report, as `YYYY-MM-DD`. It can be earlier than the day of `published_at`, which belongs to the shown article. | | `coverage.searched_from` | The start of the window, by when Itoflow stored the item | | `coverage.complete` | `true` when the reply is final: for every company, the model judged every selected candidate in the window; for a query, more judging could not change the rows | | `coverage.stored_through` | The oldest last successful read across the sources; news after it may not be stored yet. `null` before the first read. | | `coverage.judged_from` | For companies, the time from which every selected candidate is judged to the end of the window; `null` when one company has nothing judged there. For a query, the start of the window when the reply is final, else `null`. | | `coverage.judged_items` | Items the model judged during this call. A query search can judge far fewer items than it selected. | | `unknown_symbols` | Symbols you asked for, or with `monitor_id` holdings, that Itoflow has no company name for. They are skipped; search for them another way. | Results never name a monitor or its owner, and carry weights only for your own monitor through `monitor_id`. Itoflow keeps an item for 90 days when its `impact` is at least 2 or it rated the item notable or above for some company, and for 14 days otherwise. A minor company rating goes after 14 days. A token with limited scopes, such as one issued to an AI agent, needs `symbols.read`. A monitor you don't own returns `404`, the same as a missing one. An invalid parameter returns `400`; so does `q` with `symbols` or `monitor_id` (`query_with_symbols`), either story order with `q`, `symbols` or `monitor_id` (`order_with_query`), `hide_commentary=true`, `country` or `sector` without a story order (`filter_without_stories`), and `q` with more than 3 `days` (`days_exceeds_query_window`). When a model the search needs fails after its retries, the call returns `503` with `news_judge_unavailable` and no partial result; retry later. See the [market-data endpoint reference](https://docs.itoflow.ai/api-reference/coverage.md#market-data) for every field. ## Fund books used by risk measurement Risk measurement asks the factor worker to score missing names only when they have not joined its fitting universe. Each finished request adds every asked name permanently, including names it could not cover. Daily fits try the whole universe again. An immediate second run reports the coverage add's refusal reason at the same publication without asking again or waiting. Daily fit refusals use the same results. A name with no recorded reason at the pinned publication reports `not_covered`. If no worker claims a request within 60 seconds, a final status check confirms the result before measurement continues with those names unscored. When the service cannot report claim state, the wait keeps its ten-minute cap. A claimed request can use up to ten minutes in total, subject to the run's remaining time. A coverage gap does not by itself fail measurement. `POST /risk/measure` reads the newest eligible stored fund book for each model date. Each measured book and benchmark reports `fund_books`: the selected book's `book_id`, `fund_symbol`, `holdings_date` (the filing period), `as_of`, and `accepted_at`. For an N-PORT filing, `accepted_at` is its recorded filing acceptance instant; for provider or uploaded books it is `null`. The filing period is not its publication date or its latest fetch time. It remains the stored row's own period even if it is later than the model date. That metadata does not change the existing calculation rule: fund expansion is still bounded by the model date. A what-if book still has `holdings_as_of: null`: its weights came from your request, not a saved portfolio snapshot. Use `fund_books` to identify the funds looked through, not `holdings_as_of`. Empty `fund_books` means no identified stored fund book was used. Older saved answers without the field read as an empty array; that does not retroactively establish their book provenance. A later repair and rebuild may change a new answer for an old model date. Keep the book identifiers with the result when comparing runs; do not assume a model date alone fixes the holdings input. The measurement endpoint does not repair catalogue identifiers or rebuild books. Factor price inputs also check sourced daily venue limits in native prices, with one price tick of room for rounding. The check needs a dated listing record and enough observed traded sessions to prove the listing has left its exempt opening sessions. Missing age proof or native prices leave that bar unchecked. Only sourced venues with checked tick bands take this check; other venues and those with no daily limit hold nothing under this rule. A share split the provider records within seven calendar days of the bar excuses it, and each weekday without a bar adds one limit of room on each side. Stored prices and published rows stay unchanged. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.