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

# Troubleshoot monitors

> Diagnose and fix common monitor issues.

This guide helps you diagnose and resolve common monitor issues.

<Tip>
  For configuration guidance and webhook implementation, see [Configure
  monitors](/web-search-api/how-to/configure-monitors).
</Tip>

## Cannot create monitor from old job

**Symptom**: API returns "Monitor creation is only allowed for jobs with a run
window within the last 7 days."

**Cause**: Reference job's `end_date` is more than 7 days in the past.

**Solution**:

Check your job's end date:

```bash theme={null}
curl "https://catchall.newscatcherapi.com/catchAll/pull/{job_id}" \
  -H "x-api-key: YOUR_API_KEY" | jq '.date_range.end_date'
```

If older than 7 days, create a new job with `end_date` within the last 7 days
and use that as your reference.

<Note>
  Monitors require `end_date` within 7 days to avoid data gaps. The job's
  `start_date` can be any valid range - only `end_date` must be recent.
</Note>

***

## Monitor returns zero records

**Symptom**: Webhook shows `"records_count": 0` on every execution after the first.

**Possible causes**:

1. Event frequency doesn't match monitor schedule (events occur less frequently than monitor runs).
2. Deduplication is working correctly - same events keep appearing across multiple runs.
3. Reference job had very restrictive validators.

**Troubleshooting steps**:

<Steps>
  <Step title="Check reference job validators">
    Review the `validators` array in your reference job results:

    ```bash theme={null}
        curl "https://catchall.newscatcherapi.com/catchAll/pull/{reference_job_id}" \
          -H "x-api-key: YOUR_API_KEY" | jq .validators
    ```

    Overly restrictive validators may limit results.
  </Step>

  <Step title="Assess event frequency vs schedule">
    Consider whether events matching your query occur frequently enough for your monitor schedule:

    * ✅ **Good match**: Daily monitor for `"AI startup funding rounds over $10M"` (multiple events per week)

    * ❌ **Frequency mismatch**: Daily monitor for `"Unicorn IPOs in biotech sector"` (rare events)

    **If events are infrequent:**

    * Adjust monitor schedule (weekly instead of daily)
    * Expand geographic or industry scope
    * Lower thresholds (e.g., `$5M+` instead of `$50M+`)
  </Step>

  <Step title="Check monitor execution history">
    List recent monitor jobs to see the pattern:

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

    If consecutive runs return zero records, adjust event frequency or schedule.
  </Step>

  <Step title="Adjust query or schedule">
    Based on your findings:

    **Option 1 - Adjust schedule**: Change from daily to weekly/bi-weekly for rare events.

    **Option 2 - Adjust query scope**: Expand to capture more events without losing business value.

    Create new reference job → Create new monitor → Disable old monitor.
  </Step>
</Steps>

<Tip>
  Monitor deduplication uses a 7-day rolling window. Zero records after the first execution
  often means the same events keep appearing (correct deduplication), not a problem with
  your query.
</Tip>

***

## Duplicate records appearing

**Symptom**: Same event appears multiple times in aggregated results.

**Expected behavior**: The system automatically deduplicates records across
executions. If you're seeing duplicates, this indicates a potential issue.

**Troubleshooting**:

1. Check if the duplicates have different `record_id` values.
2. Verify that citations differ between duplicate records.
3. If true duplicates exist, contact support with:
   * `monitor_id`
   * `record_id` values of duplicates
   * Example records

***

## Webhook not firing

**Symptoms**:

* No POST requests received at your endpoint.
* Monitor shows jobs executing but no notifications.

**Troubleshooting steps**:

<Steps>
  <Step title="Check endpoint accessibility">
    Verify your webhook URL is publicly accessible:

    ```bash theme={null}
    curl -X POST https://your-endpoint.com/webhook \
      -H "Content-Type: application/json" \
      -d '{"test": "data"}'
    ```

    Should return 2xx status code.
  </Step>

  <Step title="Verify HTTPS">
    Ensure your webhook URL uses HTTPS (not HTTP):

    * ✅ `https://your-endpoint.com/webhook`
    * ❌ `http://your-endpoint.com/webhook`
  </Step>

  <Step title="Check firewall rules">
    Ensure your server's firewall allows incoming POST requests on the webhook
    port.
  </Step>

  <Step title="Test with webhook.site">
    Create a temporary webhook at [webhook.site](https://webhook.site) and update
    your monitor to verify the issue is with your endpoint.
  </Step>

  <Step title="Review server logs">
    Check your server logs for:

    * Incoming requests that failed
    * Authentication errors
    * Timeout errors
  </Step>
</Steps>

<Tip>
  For webhook implementation guidance including error handling and retry logic, see
  [Configure monitors: Implement robust webhooks](/web-search-api/how-to/configure-monitors#implement-robust-webhooks).
</Tip>

***

## Need more help?

If you encounter issues not covered in this guide:

1. Check the [Changelog](/web-search-api/get-started/changelog) for recent updates.
2. Review [Monitors overview](/web-search-api/concepts/monitors) for how monitors work.
3. Review [Configure monitors](/web-search-api/how-to/configure-monitors) for setup and testing guidance.
4. Contact support at [support@newscatcherapi.com](mailto:support@newscatcherapi.com) with:
   * `monitor_id` or `job_id`
   * Detailed description of the issue
   * Steps to reproduce
   * Expected vs. actual behavior