> ## Documentation Index
> Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitors

> Schedule recurring CatchAll jobs with webhook notifications.

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](/docs/web-search-api/get-started/quickstart).

## Create monitor

<Warning>
  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.
</Warning>

Once your reference job completes with `status: job_completed`, use `job_id` to
create a monitor:

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

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

  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  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;
  ```

  ```java Java theme={null}
  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");
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4",
  "status": "Monitor Created Successfully"
}
```

<Note>
  Webhooks are configured separately and attached via `webhook_ids`. For
  instructions, see [Set up webhooks](/docs/web-search-api/how-to/set-up-webhooks).
</Note>

## Retrieve results

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

### List monitors

Get all monitors for your API key:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://catchall.newscatcherapi.com/catchAll/monitors" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  from newscatcher_catchall import CatchAllApi

  client = CatchAllApi(api_key="YOUR_API_KEY")

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

  ```typescript TypeScript theme={null}
  import { CatchAllApiClient } from "newscatcher-catchall-sdk";

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

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

  ```java Java theme={null}
  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();
  ```
</CodeGroup>

Response:

<Expandable title="list monitors response">
  ```json theme={null}
  {
    "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
</Expandable>

### List monitor jobs

Get execution history for a specific monitor:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}/jobs" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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
  });
  ```

  ```java Java theme={null}
  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);
  ```
</CodeGroup>

Response:

<Expandable title="list monitor jobs response">
  ```json theme={null}
  {
    "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}`.
</Expandable>

### Get aggregated results

Retrieve all deduplicated records from all monitor jobs:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://catchall.newscatcherapi.com/catchAll/monitors/pull/{monitor_id}" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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
  });
  ```

  ```java Java theme={null}
  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);
  ```
</CodeGroup>

Response:

<Expandable title="pull monitor results response">
  ```json theme={null}
  {
    "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
</Expandable>

### 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`](/docs/web-search-api/api-reference/monitors/get-latest-monitor-results-as-csv).
It returns the latest run as a `text/csv` download — one row per record, with
enrichment fields as columns, `citations` as a JSON column, and connected
entities split into `event_associated_entities` and `mention_entities` JSON
columns.

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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",
  });
  ```

  ```java Java theme={null}
  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);
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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
  )
  ```

  ```typescript TypeScript theme={null}
  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
  });
  ```

  ```java Java theme={null}
  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()
  );
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "monitor_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4",
  "status": "Monitor updated Successfully"
}
```

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

### Enable monitor

Resume execution of a disabled monitor:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}/enable" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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 });
  ```

  ```java Java theme={null}
  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);
  ```
</CodeGroup>

Response:

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

### Disable monitor

Pause execution without deleting the monitor:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}/disable" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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 });
  ```

  ```java Java theme={null}
  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);
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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 });
  ```

  ```java Java theme={null}
  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);
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}/status" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
  }
  ```

  ```java Java theme={null}
  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())
  );
  ```
</CodeGroup>

<Expandable title="Status history response">
  ```json theme={null}
  {
    "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
      }
    ]
  }
  ```
</Expandable>

## See also

* [Set up webhooks](/docs/web-search-api/how-to/set-up-webhooks)
* [Configure monitors](/docs/web-search-api/how-to/configure-monitors)
* [Webhook payload](/docs/web-search-api/api-reference/webhooks/webhook-payload)
* [API reference](/docs/web-search-api/api-reference/monitors/create-monitor)