> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Monitor > Create a monitor; it first runs at its next scheduled time (`POST /{id}/run` runs it now). ## OpenAPI ````yaml /api-reference/agent/openapi.json post /monitors openapi: 3.1.0 info: title: NewsCatcher Agent API description: >- Agent runs (events from a query, or news about companies), company lists and monitors. Authenticate with your API key in the x-api-key header. version: 1.0.0 servers: - url: https://api.newscatcherapi.com/agent description: Production server security: [] paths: /monitors: post: tags: - monitors summary: Create Monitor description: >- Create a monitor; it first runs at its next scheduled time (`POST /{id}/run` runs it now). operationId: create_monitor_monitors_post requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateMonitorRequest' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MonitorOut' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Too Many Requests '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Service Unavailable security: - ApiKeyAuth: [] components: schemas: CreateMonitorRequest: properties: kind: type: string enum: - companies - dataset title: Kind description: >- companies: their new stories. dataset: re-run a finished research run and deliver its new rows. default: companies name: anyOf: - type: string maxLength: 120 - type: 'null' title: Name description: 'A name (default: its companies, or its topic).' companies: items: $ref: '#/components/schemas/MonitorCompanyIn' type: array title: Companies description: 'Company monitors: at least one (or list_id).' list_id: anyOf: - type: string - type: 'null' title: List Id description: >- Company monitors: a company list's id (a UUID) instead of companies. The monitor follows the list: companies added to or removed from it are monitored from the next run on. from_run_id: anyOf: - type: string format: uuid - type: 'null' title: From Run Id description: >- "Monitor this": one of your succeeded runs. An events run is re-run (same mode and columns); a companies run gives a company monitor of its companies. query: anyOf: - type: string maxLength: 5000 - type: 'null' title: Query description: >- What to watch for. Company monitors: only stories about this, e.g. "funding and acquisitions" (blank: every story about the companies; from a companies run: its query). Dataset monitors: the research request (blank: the run's query with its time window removed). topic: anyOf: - type: string maxLength: 5000 - type: 'null' title: Topic description: 'Deprecated: the old name of query for dataset monitors.' schedule: anyOf: - $ref: '#/components/schemas/ScheduleIn' - type: 'null' description: >- Default: daily at 09:00 UTC; Standard/Max dataset monitors default to weekly (today's weekday), and may run daily too. settings: $ref: '#/components/schemas/SettingsIn' conversation_id: anyOf: - type: string format: uuid - type: 'null' title: Conversation Id description: Your chat conversation where each run's result is also posted. type: object title: CreateMonitorRequest description: >- POST /monitors: a company monitor (`companies`) or a dataset monitor (`kind: dataset`, `from_run_id`). MonitorOut: properties: monitor_id: type: string format: uuid title: Monitor Id name: type: string title: Name kind: type: string title: Kind description: companies or dataset. default: companies dataset: anyOf: - additionalProperties: true type: object - type: 'null' title: Dataset description: >- Dataset monitors: topic, columns, mode, max_rows, source_run_id, window_to (where the last complete run ended). companies: items: additionalProperties: anyOf: - type: string - type: 'null' type: object type: array title: Companies description: 'Its companies now (a list monitor: its list''s).' list_id: anyOf: - type: string format: uuid - type: 'null' title: List Id description: >- The company list it follows (companies added to or removed from the list are monitored from the next run on). query: anyOf: - type: string - type: 'null' title: Query description: >- What it watches for: a company monitor's query (null: every story), a dataset monitor's research request. schedule: additionalProperties: true type: object title: Schedule settings: additionalProperties: true type: object title: Settings enabled: type: boolean title: Enabled paused_reason: anyOf: - type: string - type: 'null' title: Paused Reason description: >- Why the service paused it: "out_of_credits" (its organization's credits no longer cover it; top up, then resume) or "idle" (the organization's free monitor, its results not opened for 14 days; resume it). Null when running or paused by its user. last_opened_at: anyOf: - type: string format: date-time - type: 'null' title: Last Opened At description: >- When its owner last opened its runs, stories or rows (the free monitor pauses after 14 days without). next_run_at: anyOf: - type: string format: date-time - type: 'null' title: Next Run At description: Next scheduled run (UTC). last_run_id: anyOf: - type: string format: uuid - type: 'null' title: Last Run Id source_run_id: anyOf: - type: string format: uuid - type: 'null' title: Source Run Id description: >- The run it was made from ("Keep updated", "Monitor this"): its first run. conversation_id: anyOf: - type: string format: uuid - type: 'null' title: Conversation Id created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At type: object required: - monitor_id - name - companies - schedule - settings - enabled title: MonitorOut description: A monitor. ErrorResponse: properties: code: type: string title: Code message: type: string title: Message type: object required: - code - message title: ErrorResponse description: 'Every error: a stable code and a message to show the user.' MonitorCompanyIn: properties: domain: type: string title: Domain description: The company's website domain, e.g. stripe.com. name: anyOf: - type: string - type: 'null' title: Name description: Its name, when the domain alone is ambiguous. type: object required: - domain title: MonitorCompanyIn description: A company to follow. ScheduleIn: properties: every: type: string enum: - day - week - hours title: Every default: day at: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ title: At description: Local time, HH:MM (24-hour). default: '09:00' tz: type: string title: Tz description: IANA timezone, e.g. Europe/Berlin. default: UTC weekday: anyOf: - type: integer maximum: 6 minimum: 0 - type: 'null' title: Weekday description: 'Weekly only: 0 = Monday ... 6 = Sunday.' hours: anyOf: - type: integer maximum: 23 minimum: 1 - type: 'null' title: Hours description: >- every: hours only: hours between runs, counted from `at` each day. Refused with invalid_schedule below your plan's minimum interval (24 hours on Free and PAYG). type: object title: ScheduleIn description: >- When the monitor runs: daily (default) or weekly at a local time in a timezone, or every few hours from that time when your plan allows runs more often than daily. SettingsIn: properties: include_market_activity: type: boolean title: Include Market Activity description: >- Also market_activity stories: stock moves and analyst ratings (hidden by default). default: false type: object title: SettingsIn description: What the monitor delivers. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.