Monitors

Monitors automate data collection by running CatchAll jobs on a schedule. Create a 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 monitor

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 a 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 monitors, inspect execution history, and pull aggregated records.

List monitors

Get all 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 monitor is currently active
reference_job_query (string): Original query text from the reference job
schedule (string): Natural language schedule description
created_at (string): Monitor creation timestamp

List monitor jobs

Get execution history for a specific 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 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 monitor runs
all_records (array): Deduplicated records from all 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 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 monitors

Use these endpoints to update webhook assignments, pause, resume, or delete a monitor, and inspect its execution history.

Update monitor

Update webhook assignments or the record limit for an existing monitor. 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"
}

Schedule and reference job cannot be modified. To change the query or schedule, create a new monitor.

Enable monitor

Resume execution of a disabled monitor:

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 monitor

Pause execution without deleting the 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 monitor

Permanently delete a monitor. This action cannot be undone. Deleted 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 a 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

Libraries

Integrations

How it works

Before you begin

Create monitor

Retrieve results

List monitors

List monitor jobs

Get aggregated results

Export results as CSV

Manage monitors

Update monitor

Enable monitor

Disable monitor

Delete monitor

Get status history

See also

​How it works

​Before you begin

​Create monitor

​Retrieve results

​List monitors

​List monitor jobs

​Get aggregated results

​Export results as CSV

​Manage monitors

​Update monitor

​Enable monitor

​Disable monitor

​Delete monitor

​Get status history

​See also

How it works

Before you begin

Create monitor

Retrieve results

List monitors

List monitor jobs

Get aggregated results

Export results as CSV

Manage monitors

Update monitor

Enable monitor

Disable monitor

Delete monitor

Get status history

See also