> ## 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. # Search stored news by query, symbol or monitor > Searches the company, market and economic news and SEC filings Itoflow has stored. It selects possible matches by similarity, including items without a vector, then a model judges those candidates by meaning in any language. With `q`, the route returns one row per story, most important first. With `symbols` or `monitor_id`, a model rates matching candidates for each company, counting news about its rivals, customers, suppliers, inputs and market; then the route returns the rated items, newest first. With `monitor_id`, results are limited to that monitor’s current holdings and carry their weights. With `q`, the model judges the most important candidates first and stops once the rest could not change the rows. Judging stops after about 25 seconds; `coverage.complete` says whether the reply is final. Operation ID: get__news. ## OpenAPI ````yaml /openapi/itoflow-public.openapi.json get /news openapi: 3.1.0 info: description: >- All Itoflow APIs are experimental and may change without notice. Read-only operations marked interactive can be tried from the documentation; the others are reference-only. title: Itoflow Developer API version: 1.0.0 servers: - description: Itoflow API url: https://api.itoflow.ai security: [] tags: - name: Account - name: Billing - name: Brokers - name: Chat - name: Connected MCP servers - name: GitHub - name: Market data - name: Monitors - name: Notifications - name: Portfolios - name: Risk runs - name: Sharing and data - name: Strategies paths: /news: get: tags: - Market data summary: Search stored news by query, symbol or monitor description: >- Searches the company, market and economic news and SEC filings Itoflow has stored. It selects possible matches by similarity, including items without a vector, then a model judges those candidates by meaning in any language. With `q`, the route returns one row per story, most important first. With `symbols` or `monitor_id`, a model rates matching candidates for each company, counting news about its rivals, customers, suppliers, inputs and market; then the route returns the rated items, newest first. With `monitor_id`, results are limited to that monitor’s current holdings and carry their weights. With `q`, the model judges the most important candidates first and stops once the rest could not change the rows. Judging stops after about 25 seconds; `coverage.complete` says whether the reply is final. Operation ID: get__news. operationId: get__news parameters: - description: >- Comma-separated Itoflow symbols, at most 20. A model first rates the news for each company over the window, then an item matches when it has a rating for one of them. Symbols with no company name are skipped and listed in `unknown_symbols`. in: query name: symbols required: false schema: description: >- Comma-separated Itoflow symbols, at most 20. A model first rates the news for each company over the window, then an item matches when it has a rating for one of them. Symbols with no company name are skipped and listed in `unknown_symbols`. example: ASML.AS,NVDA.US type: string - description: >- What the news should be about, in plain words, up to 200 characters. Itoflow selects possible matches by similarity, then a model judges those candidates by meaning in any language, including items that never name the subject. Each row is then a story, and `match_p` carries the model's chance that it bears on the query. It can't be combined with `symbols` or `monitor_id` (400 `query_with_symbols`). in: query name: q required: false schema: description: >- What the news should be about, in plain words, up to 200 characters. Itoflow selects possible matches by similarity, then a model judges those candidates by meaning in any language, including items that never name the subject. Each row is then a story, and `match_p` carries the model's chance that it bears on the query. It can't be combined with `symbols` or `monitor_id` (400 `query_with_symbols`). example: chip export rules maxLength: 200 type: string - description: >- Search the current holdings of one of your monitors, rated as with `symbols`, with their weights. With `symbols` as well, only the holdings named. in: query name: monitor_id required: false schema: description: >- Search the current holdings of one of your monitors, rated as with `symbols`, with their weights. With `symbols` as well, only the holdings named. format: uuid type: string - description: >- How many days back to search, by when Itoflow stored the item: 1 to 90, default 7. With `q`, 1 to 3, default 1; more returns 400 `days_exceeds_query_window`. in: query name: days required: false schema: description: >- How many days back to search, by when Itoflow stored the item: 1 to 90, default 7. With `q`, 1 to 3, default 1; more returns 400 `days_exceeds_query_window`. maximum: 90 minimum: 1 type: integer - description: >- How to order a read without `q`, `symbols` or `monitor_id`. `newest` lists items newest first by `published_at`. `stories` folds repeats into one row per story and lists stories by the UTC day of their first report, then impact, then `published_at`, newest first. `stories_newest` folds the same stories and orders by the shown row’s `published_at` descending, then `id` descending. Either story order with `q`, `symbols` or `monitor_id` returns 400 `order_with_query`. in: query name: order required: false schema: default: newest description: >- How to order a read without `q`, `symbols` or `monitor_id`. `newest` lists items newest first by `published_at`. `stories` folds repeats into one row per story and lists stories by the UTC day of their first report, then impact, then `published_at`, newest first. `stories_newest` folds the same stories and orders by the shown row’s `published_at` descending, then `id` descending. Either story order with `q`, `symbols` or `monitor_id` returns 400 `order_with_query`. enum: - newest - stories - stories_newest type: string - description: >- Hide stories whose shown row has `is_event_p < 0.5`, before applying `limit`. Default false. True requires `order=stories` or `order=stories_newest`; otherwise returns 400 `filter_without_stories`. in: query name: hide_commentary required: false schema: default: 'false' description: >- Hide stories whose shown row has `is_event_p < 0.5`, before applying `limit`. Default false. True requires `order=stories` or `order=stories_newest`; otherwise returns 400 `filter_without_stories`. enum: - 'true' - 'false' type: string - description: >- With `order=stories` or `order=stories_newest`, only the stories with an article in the period that names this country, as an ISO 3166-1 alpha-2 code. Without a story order it returns 400 `filter_without_stories`. in: query name: country required: false schema: description: >- With `order=stories` or `order=stories_newest`, only the stories with an article in the period that names this country, as an ISO 3166-1 alpha-2 code. Without a story order it returns 400 `filter_without_stories`. example: JP pattern: ^[A-Z]{2}$ type: string - description: >- With `order=stories` or `order=stories_newest`, only the stories whose shown article has this sector. Combines with `country`. Without a story order it returns 400 `filter_without_stories`. in: query name: sector required: false schema: description: >- With `order=stories` or `order=stories_newest`, only the stories whose shown article has this sector. Combines with `country`. Without a story order it returns 400 `filter_without_stories`. enum: - economy - energy - materials - industrials - consumer_discretionary - consumer_staples - health_care - financials - information_technology - communication_services - utilities - real_estate type: string - description: >- The lowest level to return. It applies to the ratings' materiality when the call names symbols or a monitor, and to the item's impact otherwise. in: query name: min_level required: false schema: default: minor description: >- The lowest level to return. It applies to the ratings' materiality when the call names symbols or a monitor, and to the item's impact otherwise. enum: - minor - notable - material type: string - description: >- Most rows to return. With `q`, `order=stories` or `order=stories_newest`, it counts stories. in: query name: limit required: false schema: default: 20 description: >- Most rows to return. With `q`, `order=stories` or `order=stories_newest`, it counts stories. maximum: 50 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/NewsSearchResponse' description: >- With `q`, stories ranked by score. With `order=stories`, stories by first report day, then impact, then publish time. With `order=stories_newest`, the same stories by the shown row’s publish time. Otherwise matching items, newest first. '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- Invalid request. `query_with_symbols`: `q` was combined with `symbols` or `monitor_id`. `order_with_query`: `order=stories` or `order=stories_newest` was combined with `q`, `symbols` or `monitor_id`. `filter_without_stories`: `hide_commentary=true`, `country` or `sector` was sent without a story order. `days_exceeds_query_window`: `q` asked for more days than a query search covers. '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Authentication required '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Monitor not found '503': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- `news_judge_unavailable`: a model the search needs failed after its retries. Retry later; no partial result is returned. security: - bearerAuth: [] components: schemas: NewsSearchResponse: properties: coverage: properties: complete: description: >- True when the reply is final: more judging could not change its rows. With `q`, the search judges candidates from the most important down and stops once the rest could not change its rows. False when the time budget stopped the request first. With `symbols` or `monitor_id`, call again to continue; a `q` search keeps nothing, so call again with fewer `days`. type: boolean judged_from: description: >- With `symbols` or `monitor_id`, the time from which every subject is judged to the end of the window; null when a subject has nothing judged there. With `q`, the start of the window when the reply is final, else null. format: date-time type: - string - 'null' judged_items: description: >- Items the model judged in this request, for every subject. A `q` search can judge far fewer items than it selected, because it stops once the rest could not change its rows. minimum: 0 type: integer searched_from: description: The earliest `judged_at` searched. format: date-time type: string sources: description: The sources Itoflow reads news from. items: enum: - gdelt - gdelt_translingual - sec_edgar type: string type: array stored_through: description: >- Oldest last successful read across the sources; news after it may not be stored yet. Null before the first read. format: date-time type: - string - 'null' required: - sources - searched_from - complete - stored_through - judged_from - judged_items type: object items: description: >- With `q`, stories ranked by `match_p` × impact ÷ 3, newest first on ties. With `order=stories`, stories by the UTC day of their first report, then impact, then `published_at`, newest first. With `order=stories_newest`, the same stories by the shown row’s `published_at` descending, then `id` descending. With `q` or either story order, `limit` counts stories. Otherwise, matching items newest first by `published_at`. items: properties: countries: description: >- 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. items: pattern: ^[A-Z]{2}$ type: string maxItems: 3 type: array id: description: News item ID, shared by every monitor it reaches. format: uuid type: string impact: description: >- Expected level for how much the news could move the companies or markets it concerns: 0 none, 1 minor, 2 notable, 3 material. maximum: 3 minimum: 0 type: number is_event_p: description: >- Probability that the item reports an event rather than commentary. maximum: 1 minimum: 0 type: number language: description: BCP 47 tag of the title. minLength: 2 type: string level: description: >- With `symbols` or `monitor_id`, the level of the top matching pair; otherwise the level of `impact`. enum: - minor - notable - material type: string match_p: description: >- With `q`, the model's chance that the item bears on the query. Null without `q`. maximum: 1 minimum: 0 type: - number - 'null' published_at: format: date-time type: string publisher: type: - string - 'null' repeat_of: description: An earlier item that reports the same event. format: uuid type: - string - 'null' repeats: description: >- With `q`, the number of other matches folded into this story by `repeat_of`. With `order=stories` or `order=stories_newest`, the number of the story's other articles in the period. 0 otherwise. minimum: 0 type: integer sec_form: description: The SEC form, such as 8-K, for a filing. Null for news. type: - string - 'null' sector: description: >- The sector the article is about: one of the 11 GICS sectors, or `economy` for the economy as a whole. Null when the article has not been sorted. enum: - economy - energy - materials - industrials - consumer_discretionary - consumer_staples - health_care - financials - information_technology - communication_services - utilities - real_estate - null type: - string - 'null' source: description: The source the item came from. enum: - gdelt - gdelt_translingual - sec_edgar type: string story_day: description: >- 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 story's highest-impact article. Absent otherwise. pattern: ^\d{4}-\d{2}-\d{2}$ type: string symbols: description: >- The item's pairs that matched: for the asked symbols, or for the monitor's holdings with `monitor_id`. Highest materiality first. Empty when the call names neither. items: properties: direction: description: Whether the news is good or bad for the company. enum: - good - bad - mixed - unclear type: string direction_p: description: Probability of the direction. maximum: 1 minimum: 0 type: number level: description: >- `material` from 2.5, `notable` from 1.5, otherwise `minor`. enum: - minor - notable - material type: string materiality: description: >- Expected level for how much the news could change the company's value: 1 minor, 2 notable, 3 material. Only pairs rated 1 or above are stored. maximum: 3 minimum: 1 type: number symbol: description: Itoflow symbol of the company. maxLength: 30 minLength: 1 type: string valuation_unavailable_reason: description: >- Why the weight is null: net assets are unknown or not positive, or an open holding that carries the company has no usable price. type: string weight: description: >- With `monitor_id`, the holding's current share of that monitor portfolio's net assets, a short counted by its size; null for research monitors, when the portfolio's net assets are unknown or not positive, and when an open holding that carries the company has no usable price. Always null without `monitor_id`. minimum: 0 type: - number - 'null' required: - symbol - weight - materiality - level - direction - direction_p type: object type: array title: description: As published, in its own language. maxLength: 300 minLength: 1 type: string title_en: description: >- The title in English. Null when the title is in English, the model couldn't translate it, or the backfill hasn't reached it. maxLength: 600 minLength: 1 type: - string - 'null' url: description: Link to the article or filing. format: uri type: string required: - id - source - url - title - language - publisher - published_at - is_event_p - repeat_of - title_en - sec_form - level - impact - symbols - match_p - repeats - countries - sector type: object type: array unknown_symbols: description: >- Asked symbols, or with `monitor_id` the holdings, skipped because Itoflow has no company name for them. items: type: string type: array required: - items - coverage - unknown_symbols type: object Error: properties: available: description: Optional available amount or value type: string billing_action: $ref: '#/components/schemas/BillingAction' code: description: Machine-readable error code type: string currentVersion: description: Current server-side version, when relevant type: number details: description: Optional structured error details error: description: Error type or code type: string expectedVersion: description: Client-provided expected version, when relevant type: number message: description: Human-readable error message type: string requested: description: Optional requested amount or value type: string usage: description: Optional usage metadata for limit errors required: - error type: object BillingAction: description: Action that resolves a billing-related rejection properties: href: type: string kind: enum: - upgrade - payment_method - spending_cap - billing type: string label: type: string required: - href - label - kind type: object securitySchemes: bearerAuth: bearerFormat: JWT description: Itoflow access token issued for the Itoflow API. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.