> ## 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. # Read news for a monitor > Returns news from the last 24 hours that reaches one monitor's holdings or matches its mandate, and the state of the news reader. Without `since`, items come ranked by materiality and holding size, the top first; with `since`, items with a match judged after that time come newest first. `feed.coverage` says how many of the monitor's subjects are judged through the last 24 hours. When `current` is below `subjects`, call `fetchMonitorNews` once, then call this again every few seconds, passing `judged_through` as `since`, until `current` equals `subjects`. A missing monitor, one you do not own, and one being deleted all return the same 404. Operation ID: getMonitorNews. ## OpenAPI ````yaml /openapi/itoflow-public.openapi.json get /watchlists/{id}/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: /watchlists/{id}/news: get: tags: - Monitors summary: Read news for a monitor description: >- Returns news from the last 24 hours that reaches one monitor's holdings or matches its mandate, and the state of the news reader. Without `since`, items come ranked by materiality and holding size, the top first; with `since`, items with a match judged after that time come newest first. `feed.coverage` says how many of the monitor's subjects are judged through the last 24 hours. When `current` is below `subjects`, call `fetchMonitorNews` once, then call this again every few seconds, passing `judged_through` as `since`, until `current` equals `subjects`. A missing monitor, one you do not own, and one being deleted all return the same 404. Operation ID: getMonitorNews. operationId: getMonitorNews parameters: - description: Monitor UUID in: path name: id required: true schema: format: uuid type: string - description: Maximum items to return, from 1 to 200. in: query name: limit required: false schema: default: 200 maximum: 200 minimum: 1 type: integer - description: >- Return only items with a holding or mandate match judged after this time, newest first, each with all its matches. The read reaches 5 minutes before this time to catch matches that were saved late, so merge items by `id`. A page that comes back with `limit` items may have left older ones out, so read once without `since` instead. Use ISO 8601 with a zone, such as 2026-09-25T12:00:00Z. in: query name: since required: false schema: format: date-time type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Gateway_MonitorNewsResponse' description: News feed '400': content: application/json: schema: $ref: '#/components/schemas/Gateway_MonitorNewsError' description: Invalid limit or since '401': description: Authentication required. '404': content: application/json: schema: $ref: '#/components/schemas/Gateway_MonitorNewsError' description: Monitor not found security: - bearerAuth: [] components: schemas: Gateway_MonitorNewsResponse: additionalProperties: false properties: feed: additionalProperties: false properties: coverage: additionalProperties: false description: How many of the subjects are current. properties: current: description: >- Subjects judged through the last 24 hours. A mandate counts only when it was judged for its current text. maximum: 9007199254740991 minimum: 0 type: integer subjects: description: 'The monitor''s subjects: its companies and its mandate.' maximum: 9007199254740991 minimum: 0 type: integer required: - subjects - current type: object judged_through: anyOf: - format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ type: string - type: 'null' description: >- The newest time a holding pair or a mandate match was judged among the items this read matched, including any past `limit`. Pass it as `since` on the next poll. Null when nothing matched; keep the earlier value then. largest_weight: anyOf: - minimum: 0 type: number - type: 'null' description: >- The book's largest holding weight, which the score divides by. Null for research monitors. last_success_at: anyOf: - format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ type: string - type: 'null' description: >- Oldest last successful read across news sources. Null before the first read. paused: description: True while the monitor is paused. type: boolean window_hours: const: 24 description: Hours of news the feed covers. type: number required: - last_success_at - paused - window_hours - largest_weight - judged_through - coverage type: object items: description: >- Items that reach a holding or match the mandate. Without `since`, the top items by the default score, where a mandate match scores as a holding with materiality `mandate_p` × `impact` and weight 0, and an item matched both ways takes the larger score; with `since`, items with a holding pair or a mandate match judged after 5 minutes before it, newest first, each with all its matches. Mandate matches show only when they were judged for the current mandate text. items: additionalProperties: false properties: direction: anyOf: - description: Whether the news is good or bad for the company. enum: - good - bad - mixed - unclear type: string - type: 'null' description: >- The top holding's direction. Null when only the mandate matched. direction_p: anyOf: - maximum: 1 minimum: 0 type: number - type: 'null' description: >- Probability of the top holding's direction. Null when only the mandate matched. holdings: description: >- The monitor's holdings the item reaches, top holding first by the default score. Empty when only the mandate matched. items: additionalProperties: false 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 holding. 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: anyOf: - minimum: 0 type: number - type: 'null' description: >- The holding's current share of the portfolio's net assets, a short counted by its size. Null for research monitors and a portfolio worth nothing or less. An open holding without usable price, currency or exchange-rate evidence makes every weight null; in a live mirror valued at its broker total, only the weights of the companies it carries. required: - symbol - weight - materiality - level - direction - direction_p type: object type: array id: description: News item ID, shared by every monitor it reaches. format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ 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 judged_at: format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ type: string language: description: BCP 47 tag of the title. minLength: 2 type: string level: anyOf: - description: >- `material` from 2.5, `notable` from 1.5, otherwise `minor`. enum: - minor - notable - material type: string - type: 'null' description: The top holding's level. Null when only the mandate matched. mandate_p: anyOf: - maximum: 1 minimum: 0 type: number - type: 'null' description: >- Probability that the item bears on the monitor's mandate, at or above the mandate bar. Null when only holdings matched, and while the mandate's matches were judged for an earlier text. materiality: anyOf: - 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 - type: 'null' description: >- The top holding's materiality. Null when only the mandate matched. published_at: format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ type: string publisher: type: - string - 'null' repeat_of: anyOf: - format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ type: string - type: 'null' description: An earlier item that reports the same event. source: description: The source the item came from. enum: - gdelt - gdelt_translingual - sec_edgar type: string title: description: As published, in its own language. maxLength: 300 minLength: 1 type: string title_en: anyOf: - maxLength: 600 minLength: 1 type: string - type: 'null' 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. url: description: Link to the article or filing. format: uri type: string required: - id - source - url - title - title_en - language - publisher - published_at - materiality - level - direction - direction_p - holdings - mandate_p - is_event_p - impact - repeat_of - judged_at type: object type: array required: - items - feed type: object Gateway_MonitorNewsError: additionalProperties: false properties: error: enum: - INVALID_REQUEST - NOT_FOUND type: string message: type: string required: - error - message 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.