Event Monitors

Event Monitors automate data collection by running CatchAll jobs on a schedule. Create an event monitor from a successful job, define when to run it, and receive webhook notifications when new results are available.

How it works

Each scheduled execution does the following:

Creates a new job with its own job_id.
Uses a rolling date window based on schedule frequency.
Applies the reference job’s validators, extractors, and schema.
Deduplicates records across all runs and merges the results.

Before you begin

Create a successful job following the Quickstart guide.

Create event monitor

Event Monitors require a reference job with end_date within the last 7 days. If your reference job is older than 7 days, submit a new job first.

Once your reference job completes with status: job_completed, use job_id to create an event monitor:

curl -X POST "https://catchall.newscatcherapi.com/catchAll/monitors/create" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_job_id": "295b95d8-6041-4f4b-b132-9f009fc6af70",
    "schedule": "every day at 12 PM UTC",
    "webhook_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

{
  "reference_job_id": "295b95d8-6041-4f4b-b132-9f009fc6af70",
  "schedule": "every day at 12 PM UTC",
  "webhook_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")

# Create a monitor
monitor = client.monitors.create_monitor(
    reference_job_id="295b95d8-6041-4f4b-b132-9f009fc6af70",
    schedule="every day at 12 PM UTC",
    webhook_ids=["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
)

monitor_id = monitor.monitor_id

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });

// Create a monitor
const monitor = await client.monitors.createMonitor({
  reference_job_id: "295b95d8-6041-4f4b-b132-9f009fc6af70",
  schedule: "every day at 12 PM UTC",
  webhook_ids: ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
});

const monitorId = monitor.monitor_id;

import com.newscatcher.catchall.CatchAllApi;
import com.newscatcher.catchall.resources.monitors.requests.CreateMonitorRequestDto;
import com.newscatcher.catchall.types.WebhookDto;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

// Create a monitor
var monitor = client.monitors().createMonitor(
    CreateMonitorRequestDto.builder()
        .referenceJobId("295b95d8-6041-4f4b-b132-9f009fc6af70")
        .schedule("every day at 12 PM UTC")
        .webhookIds(List.of("a1b2c3d4-e5f6-7890-abcd-ef1234567890"))
        .build()
);

String monitorId = monitor.getMonitorId().orElse("N/A");

Response:

{
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4",
  "status": "Monitor Created Successfully"
}

Webhooks are configured separately and attached via webhook_ids. For instructions, see Set up webhooks.

Retrieve results

Use these endpoints to list event monitors, inspect execution history, and pull aggregated records.

List event monitors

Get all event monitors for your API key:

curl "https://catchall.newscatcherapi.com/catchAll/monitors" \
  -H "x-api-key: YOUR_API_KEY"

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")

# List all monitors
monitors = client.monitors.list_monitors()

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });

// List all monitors
const monitors = await client.monitors.listMonitors();

import com.newscatcher.catchall.CatchAllApi;
import com.newscatcher.catchall.types.ListMonitorsResponseDto;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

// List all monitors
ListMonitorsResponseDto monitors = client.monitors().listMonitors();

Response:

Show list monitors response

{
  "total_monitors": 2,
  "monitors": [
    {
      "monitor_id": "0bcbf554-1f38-460e-9f6d-4bb9338560a4",
      "reference_job_id": "2acada6a-3e55-423d-9406-00f5c6dc73da",
      "reference_job_query": "Cross-border mergers and acquisitions involving US companies",
      "enabled": false,
      "schedule": "every day at 12 PM UTC",
      "timezone": "UTC",
      "created_at": "2025-11-04T21:04:22Z"
    },
    {
      "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4",
      "reference_job_id": "295b95d8-6041-4f4b-b132-9f009fc6af70",
      "reference_job_query": "AI company acquisitions and mergers",
      "enabled": true,
      "schedule": "every Monday at 9 AM EST",
      "timezone": "EST",
      "created_at": "2025-11-07T10:54:42Z"
    }
  ]
}

Key fields:

enabled (boolean): Whether the event monitor is currently active
reference_job_query (string): Original query text from the reference job
schedule (string): Natural language schedule description
created_at (string): Event monitor creation timestamp

List event monitor jobs

Get execution history for a specific event monitor:

curl "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}/jobs" \
  -H "x-api-key: YOUR_API_KEY"

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")
monitor_id = "3fec5b07-8786-46d7-9486-d43ff67eccd4"

# List monitor jobs
jobs = client.monitors.list_monitor_jobs(monitor_id)

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });
const monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

// List monitor jobs
const jobs = await client.monitors.listMonitorJobs({
  monitor_id: monitorId
});

import com.newscatcher.catchall.CatchAllApi;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

String monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

// List monitor jobs
var jobs = client.monitors().listMonitorJobs(monitorId);

Response:

Show list monitor jobs response

{
  "monitor_id": "3fec5b07-8786-86d7-9486-d43ff67eccd4",
  "sort_order": "asc",
  "total_jobs": 2,
  "jobs": [
    {
      "job_id": "8a9763dd-3611-4b3b-a6cf-3e893a0c6746",
      "start_date": "2025-11-07T10:50:00Z",
      "end_date": "2025-11-07T10:55:00Z"
    },
    {
      "job_id": "288387df-7e05-4722-83cc-ecbebb6d8123",
      "start_date": "2025-11-07T10:55:00Z",
      "end_date": "2025-11-07T11:00:00Z"
    }
  ]
}

Use the job_id to retrieve detailed results for a specific execution via /catchAll/pull/{job_id}.

Get aggregated results

Retrieve all deduplicated records from all event monitor jobs:

curl "https://catchall.newscatcherapi.com/catchAll/monitors/pull/{monitor_id}" \
  -H "x-api-key: YOUR_API_KEY"

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")
monitor_id = "3fec5b07-8786-46d7-9486-d43ff67eccd4"

# Get aggregated results
results = client.monitors.pull_monitor_results(monitor_id)

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });
const monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

// Get aggregated results
const results = await client.monitors.pullMonitorResults({
  monitor_id: monitorId
});

import com.newscatcher.catchall.CatchAllApi;
import com.newscatcher.catchall.types.PullMonitorResponseDto;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

String monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

// Get aggregated results
PullMonitorResponseDto results = client.monitors().pullMonitorResults(monitorId);

Response:

Show pull monitor results response

{
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4",
  "cron_expression": "0 12 * * *",
  "timezone": "UTC",
  "reference_job": {
    "query": "AI company acquisitions and mergers",
    "context": "Focus on technology companies, include deal size if mentioned"
  },
  "run_info": {
    "first_run": "2025-11-07T10:50:00Z",
    "last_run": "2025-11-07T11:30:00Z"
  },
  "records": 2,
  "status": "Done",
  "all_records": [
    {
      "record_id": "6417909601438475967",
      "record_title": "Samsung Electronics Acquires Oxford Semantic Technologies",
      "added_on": "2025-11-07T10:55:00Z",
      "enrichment": {
        "acquiring_company": "Samsung Electronics",
        "acquired_company": "Oxford Semantic Technologies",
        "acquisition_date": "2024",
        "deal_type": "acquisition",
        "ai_technology_focus": ["knowledge graphs", "personalized AI"],
        "confidence": "high"
      },
      "citations": [
        {
          "title": "Samsung invests in AI and M&A",
          "link": "https://n.news.naver.com/mnews/article/629/0000441563",
          "published_date": "2025-11-07T11:15:11Z",
          "job_id": "c4cb35e9-c8a5-46bc-87aa-5fdbf36f8e33",
          "added_on": "2025-11-07T10:55:00Z"
        }
      ],
      "added_on": "2025-11-07T10:55:00Z",
      "updated_on": "2025-11-07T10:55:00Z"
    }
  ]
}

Key fields:

cron_expression (string): Parsed cron format from your natural language schedule
reference_job (object): Original query and context from the reference job
run_info (object): Execution timeframe showing first and last event monitor runs
all_records (array): Deduplicated records from all event monitor executions

Export results as CSV

To download the most recent run’s records as a spreadsheet-friendly file, use GET /catchAll/monitors/pull/{monitor_id}/csv. It returns the latest run as a text/csv download — one row per record, with enrichment fields as columns and citations as a JSON column. If the event monitor’s reference job used a connected entity dataset, connected entities are split into event_associated_entities and mention_entities JSON columns. When no entity dataset was used, those two columns are omitted from the export entirely rather than included as empty columns — read columns by header name so both shapes parse correctly.

curl "https://catchall.newscatcherapi.com/catchAll/monitors/pull/3fec5b07-8786-46d7-9486-d43ff67eccd4/csv" \
  -H "x-api-key: YOUR_API_KEY" \
  -o monitor-results.csv

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")

csv_data = client.monitors.pull_monitor_results_csv(
    monitor_id="3fec5b07-8786-46d7-9486-d43ff67eccd4"
)
with open("monitor-results.csv", "wb") as f:
    f.write(csv_data)

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });

const csvData = await client.monitors.pullMonitorResultsCsv({
  monitor_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4",
});

import com.newscatcher.catchall.CatchAllApi;
import java.nio.file.*;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

byte[] csvData = client.monitors().pullMonitorResultsCsv(
    "3fec5b07-8786-46d7-9486-d43ff67eccd4"
);
Files.write(Paths.get("monitor-results.csv"), csvData);

For agentic workflows and data pipelines, use the JSON endpoint instead. CSV and Excel are notorious for silent encoding issues, truncated long-text fields, and mangled special characters — problems that are hard to catch and harder to debug downstream.

Manage event monitors

Use these endpoints to update webhook assignments, record limit, or schedule; pause, resume, or delete an event monitor; and inspect its execution history.

Update event monitor

Update webhook assignments, the record limit, or the schedule for an existing event monitor. Omitted fields are left unchanged. Pass a new list of webhook IDs to replace existing assignments. Pass an empty array to clear all assignments:

curl -X PATCH "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "limit": 100
  }'

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")

client.monitors.update_monitor(
    monitor_id="3fec5b07-8786-46d7-9486-d43ff67eccd4",
    webhook_ids=["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    limit=100
)

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });

await client.monitors.updateMonitor({
  monitor_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4",
  webhook_ids: ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  limit: 100
});

import com.newscatcher.catchall.CatchAllApi;
import com.newscatcher.catchall.resources.monitors.requests.UpdateMonitorRequestDto;
import java.util.List;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

client.monitors().updateMonitor(
    "3fec5b07-8786-46d7-9486-d43ff67eccd4",
    UpdateMonitorRequestDto.builder()
        .webhookIds(List.of("a1b2c3d4-e5f6-7890-abcd-ef1234567890"))
        .limit(100)
        .build()
);

Response:

{
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4",
  "status": "Monitor updated Successfully"
}

Change the schedule

Pass schedule to replace the event monitor’s current schedule without recreating it. The event monitor keeps its ID, reference job, webhooks, and execution history:

curl -X PATCH "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "every Monday at 9 AM EST"
  }'

{
  "schedule": "every Monday at 9 AM EST"
}

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")

client.monitors.update_monitor(
    monitor_id="3fec5b07-8786-46d7-9486-d43ff67eccd4",
    schedule="every Monday at 9 AM EST",
)

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });

await client.monitors.updateMonitor({
  monitor_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4",
  schedule: "every Monday at 9 AM EST",
});

import com.newscatcher.catchall.CatchAllApi;
import com.newscatcher.catchall.resources.monitors.requests.UpdateMonitorRequestDto;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

client.monitors().updateMonitor(
    "3fec5b07-8786-46d7-9486-d43ff67eccd4",
    UpdateMonitorRequestDto.builder()
        .schedule("every Monday at 9 AM EST")
        .build()
);

schedule uses the same natural-language format as event monitor creation.
timezone (optional, default UTC) sets an IANA timezone for the new schedule, such as America/New_York. A timezone in the schedule text takes precedence. timezone is ignored if schedule is not set.
The new schedule takes effect from the next scheduler reload, and the old schedule stops firing.
The API returns 422 if the schedule can’t be parsed or runs would be spaced too closely.

The reference job cannot be modified. To change the query, validators, or enrichments, create a new event monitor from a different reference job.

Enable event monitor

Resume execution of a disabled event monitor:

If your account runs out of credits, event monitors are disabled automatically, and you get an email (at most one per day). After adding credits, enable the event monitor again to resume scheduled runs.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}/enable" \
  -H "x-api-key: YOUR_API_KEY"

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")
monitor_id = "3fec5b07-8786-46d7-9486-d43ff67eccd4"

# Enable monitor
client.monitors.enable_monitor(monitor_id)

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });
const monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

// Enable monitor
await client.monitors.enableMonitor({ monitor_id: monitorId });

import com.newscatcher.catchall.CatchAllApi;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

String monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

// Enable monitor
client.monitors().enableMonitor(monitorId);

Response:

{
  "success": true,
  "message": "Monitor enabled successfully.",
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4"
}

Disable event monitor

Pause execution without deleting the event monitor:

curl -X POST "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}/disable" \
  -H "x-api-key: YOUR_API_KEY"

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")
monitor_id = "3fec5b07-8786-46d7-9486-d43ff67eccd4"

# Disable monitor
client.monitors.disable_monitor(monitor_id)

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });
const monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

// Disable monitor
await client.monitors.disableMonitor({ monitor_id: monitorId });

import com.newscatcher.catchall.CatchAllApi;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

String monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

// Disable monitor
client.monitors().disableMonitor(monitorId);

Response:

{
  "success": true,
  "message": "Monitor disabled successfully.",
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4"
}

Delete event monitor

Permanently delete an event monitor. This action cannot be undone. Deleted event monitors stop executing immediately and no longer appear in list results.

curl -X DELETE "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}" \
  -H "x-api-key: YOUR_API_KEY"

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")
monitor_id = "3fec5b07-8786-46d7-9486-d43ff67eccd4"

client.monitors.delete_monitor(monitor_id)

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });
const monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

await client.monitors.deleteMonitor({ monitor_id: monitorId });

import com.newscatcher.catchall.CatchAllApi;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

String monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

client.monitors().deleteMonitor(monitorId);

Response:

{
  "success": true,
  "message": "Monitor deleted successfully.",
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4"
}

Get status history

Get the full execution history of an event monitor as a list of status entries, ordered from newest to oldest. Each entry records a lifecycle event — creation, enable/disable, a scheduled run, or a completed dump with record counts and webhook delivery result.

curl "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}/status" \
  -H "x-api-key: YOUR_API_KEY"

from newscatcher_catchall import CatchAllApi

client = CatchAllApi(api_key="YOUR_API_KEY")
monitor_id = "3fec5b07-8786-46d7-9486-d43ff67eccd4"

history = client.monitors.get_monitor_status_history(monitor_id)
for entry in history.statuses:
    print(f"{entry.status}: {entry.created_at}")

import { CatchAllApiClient } from "newscatcher-catchall-sdk";

const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });
const monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

const history = await client.monitors.getMonitorStatusHistory({
  monitor_id: monitorId,
});
for (const entry of history.statuses) {
  console.log(`${entry.status}: ${entry.created_at}`);
}

import com.newscatcher.catchall.CatchAllApi;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

String monitorId = "3fec5b07-8786-46d7-9486-d43ff67eccd4";

var history = client.monitors().getMonitorStatusHistory(monitorId);
history.getStatuses().forEach(entry ->
    System.out.println(entry.getStatus() + ": " + entry.getCreatedAt())
);

Show Status history response

{
  "success": true,
  "message": null,
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4",
  "total_statuses": 5,
  "statuses": [
    {
      "status": "dump",
      "created_at": "2026-02-05T12:04:00Z",
      "additional_information": {
        "nb_existing_records": 408,
        "nb_final_records": 28
      }
    },
    {
      "status": "scheduled",
      "created_at": "2026-02-05T12:00:00Z",
      "additional_information": {
        "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
        "start_date": "2026-02-04T12:00:00",
        "end_date": "2026-02-05T12:00:00"
      }
    },
    {
      "status": "created",
      "created_at": "2026-01-19T16:28:00Z",
      "additional_information": null
    }
  ]
}

Get started

Concepts

How to

API Reference

Integrations

Libraries

How it works

Before you begin

Create event monitor

Retrieve results

List event monitors

List event monitor jobs

Get aggregated results

Export results as CSV

Manage event monitors

Update event monitor

Change the schedule

Enable event monitor

Disable event monitor

Delete event monitor

Get status history

See also

​How it works

​Before you begin

​Create event monitor

​Retrieve results

​List event monitors

​List event monitor jobs

​Get aggregated results

​Export results as CSV

​Manage event monitors

​Update event monitor

​Change the schedule

​Enable event monitor

​Disable event monitor

​Delete event monitor

​Get status history

​See also

How it works

Before you begin

Create event monitor

Retrieve results

List event monitors

List event monitor jobs

Get aggregated results

Export results as CSV

Manage event monitors

Update event monitor

Change the schedule

Enable event monitor

Disable event monitor

Delete event monitor

Get status history

See also