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

# bigdata_get_monitor_runs

> Read a search monitor's run history, or the results of a flash or full simulation.

## Overview

The `bigdata_get_monitor_runs` tool reads the runs of a search monitor and the events each run found. It reads one of three things, depending on what you pass:

* **History** (no `simulation_id`): the monitor's past runs
* **Flash simulation** (`simulation_id` and `mode: "flash"`): the result of a flash preview
* **Full simulation** (`simulation_id` and `mode: "full"`): the replayed runs of a full simulation

Start simulations with [`bigdata_simulate_monitor`](https://docs.bigdata.com/mcp-reference/tools/bigdata-simulate-monitor).

## When to Use

Get Monitor Runs is ideal for:

* **Reviewing a preview:** Reading a flash simulation before activating a monitor
* **Backtesting:** Reading the runs of a full simulation over a past period
* **Checking alerts:** Reading what an active monitor found on its recent runs

## How It Works

1. **Start** a simulation with [`bigdata_simulate_monitor`](https://docs.bigdata.com/mcp-reference/tools/bigdata-simulate-monitor), or skip this step to read history
2. **Call** `bigdata_get_monitor_runs` with the `monitor_id`, plus the `simulation_id` and `mode` it returned
3. **Poll** a full simulation every 10 to 15 seconds until `simulation.phase` is `completed` or `failed`. A flash read waits inside the call

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `monitor_id` | string | Yes | ID of the monitor. |
| `simulation_id` | string | No | Simulation ID from `bigdata_simulate_monitor`. Omit to read history. |
| `mode` | string | With `simulation_id` | `flash` or `full`. Must be the mode `bigdata_simulate_monitor` returned. |
| `run_id` | string | No | Read one run. History and full only. |
| `status` | string | No | Filter runs by status. History and full only. |
| `start_timestamp` | string | No | Earliest time a run executed. History only. |
| `end_timestamp` | string | No | Latest time a run executed. History only. |
| `limit` | integer (1-20) | No | Number of runs. Defaults to 1 for history and 20 for full. Ignored for flash. |
| `include_events` | boolean | No | Include the events of each run. Defaults to `false` for history and `true` for full. Always on for flash. |

What each read accepts:

| | History | Flash simulation | Full simulation |
| - | - | - | - |
| `simulation_id` and `mode` | Omit both | `mode: "flash"` | `mode: "full"` |
| `run_id`, `status` | Yes | Rejected | Yes |
| `start_timestamp`, `end_timestamp` | Yes | Rejected | Rejected |
| `limit` | Default 1 | Ignored | Default 20 |
| `include_events` | Default `false` | Always on | Default `true` |

**Flash simulation**

```json theme={null}
{
  "monitor_id": "b0253b18-0dd8-4a01-a9a4-f209bce91a26",
  "simulation_id": "01a1c4ff-ed97-7581-8969-fa059a3a44ce",
  "mode": "flash"
}
```

**History**

```json theme={null}
{
  "monitor_id": "b0253b18-0dd8-4a01-a9a4-f209bce91a26",
  "limit": 5,
  "include_events": true
}
```

### Important Notes

* Reading with the wrong `mode` returns an error that names the right mode, once a worker has had about 60 seconds to pick up the job
* A flash read waits up to 25 seconds inside the call, checking every 3 seconds
* An unknown or expired flash `simulation_id` returns a not-found error. Previews expire after 7 days, or after 30 minutes if they never started
* A flash simulation that failed before reading any news returns an error, not an empty page
* History includes full-simulation runs, marked `is_simulation: true`. They are replays, not alerts that were sent
* If the page of runs is too large, the call returns an error. Lower `limit` or set `include_events` to `false`

## Data Returned

| Field | Description |
| - | - |
| `runs` | Runs read, each with its window, status, and events |
| `simulation` | Progress of the simulation. `null` when reading history |

Each run has:

| Field | Description |
| - | - |
| `id` | Run ID |
| `status` | Run status, for example `COMPLETED` |
| `is_simulation` | `true` for simulated runs |
| `simulation_id` | Simulation ID, for simulated runs |
| `window_start`, `window_end` | Time window the run covered |
| `event_count` | Number of events found |
| `events` | Events found, when `include_events` is on. Each has a `summary`, the extracted fields, a `novel` flag, and `grounding` sources |
| `usage` | Usage for the run, or `null` |

Each event has:

| Field | Description |
| - | - |
| `id` | Event ID |
| `summary` | Short summary of the event, written by the system |
| `novel` | Whether the event is new. Not judged in flash previews |
| Schema fields | One key per field in the monitor's [structured output](https://docs.bigdata.com/mcp-reference/tools/bigdata-create-monitor.md#structured-output). `entity_reference` fields come back as `{name, rp_entity_id}`, with `rp_entity_id` set to `null` when the entity could not be resolved. Fields not stated in the source are `null` |
| `grounding` | Source documents for the event, each with `headline`, `source`, `url`, the chunk numbers in `cnum`, and `timestamp` |

`simulation.phase` goes `accepted`, `seeding`, `running`, and ends at `completed` or `failed`. Stop polling at either of the last two.

A flash preview of the [Anthropic – Regulatory Watch](https://docs.bigdata.com/mcp-reference/tools/bigdata-create-monitor.md#data-returned) monitor, which found two events in the latest four-hour window. The second event's `grounding` is cut to two of its eight sources:

```json theme={null}
{
  "runs": [
    {
      "id": "7a53af9a-8add-4d3e-8409-65fc1d752d66",
      "status": "COMPLETED",
      "is_simulation": true,
      "simulation_id": "01a1c4ff-ed97-7581-8969-fa059a3a44ce",
      "window_start": "2026-11-10T06:00:00Z",
      "window_end": "2026-11-10T10:00:00Z",
      "event_count": 2,
      "events": [
        {
          "id": "01a1c4ff-ed97-7581-8969-fa059a3a44ce:3",
          "summary": "A federal judge in California allowed claims to proceed against Anthropic over marketing Claude Max subscriptions as providing “5x or 20x more usage” than lower-priced plans, while dismissing other claims.",
          "novel": false,
          "status": "concluded",
          "jurisdiction": "California",
          "issue_at_stake": "Alleged deceptive advertising, negligent misrepresentation and breach of contract involving Claude Max subscription usage claims",
          "potential_penalties": null,
          "regulator": {
            "name": "US Magistrate Judge Alex Tse",
            "rp_entity_id": null
          },
          "target_company": {
            "name": "Anthropic PBC",
            "rp_entity_id": "IWGWUR"
          },
          "action_type": "enforcement",
          "grounding": [
            {
              "id": "4D10E3A3910F98F6BE457020EF93DD00",
              "headline": "Anthropic Must Face Lawsuit Over Claude Subscription Marketing",
              "source": {
                "id": "7E64B4",
                "name": "NDTV"
              },
              "url": "https://app.bigdata.com/documents/4D10E3A3910F98F6BE457020EF93DD00?cnum=1",
              "cnum": [
                1
              ],
              "timestamp": "2026-11-10T06:20:13"
            }
          ]
        },
        {
          "id": "01a1c4ff-ed97-7581-8969-fa059a3a44ce:1",
          "summary": "The Personal Information Protection Commission (PIPC) launched a full-scale investigation into a leak affecting 112 domestic corporate accounts using Anthropic's Claude service, examining possible violations of the Personal Information Protection Act and possible involvement of an external security firm.",
          "novel": false,
          "status": "opened",
          "jurisdiction": "Korea",
          "issue_at_stake": "Leak of account information from 112 domestic corporate accounts using Claude; possible violations of the Personal Information Protection Act and possible leakage by an external security firm.",
          "potential_penalties": null,
          "regulator": {
            "name": "Personal Information Protection Commission of South Korea",
            "rp_entity_id": "1605E0"
          },
          "target_company": {
            "name": "Anthropic PBC",
            "rp_entity_id": "IWGWUR"
          },
          "action_type": "investigation",
          "grounding": [
            {
              "id": "6F7E47693EA7D1F504CD5C06A8D8A63E",
              "headline": "PIPC launches formal investigation into Anthropic 'Claude' personal information leak",
              "source": {
                "id": "4DDE06",
                "name": "Yonhap News"
              },
              "url": "https://app.bigdata.com/documents/6F7E47693EA7D1F504CD5C06A8D8A63E?cnum=1",
              "cnum": [
                1,
                2
              ],
              "timestamp": "2026-11-10T07:24:56"
            },
            {
              "id": "94D398DC4659EA44555D1422A878EB4F",
              "headline": "PIPC Launches Investigation into Anthropic Data Breach",
              "source": {
                "id": "521086",
                "name": "Edaily"
              },
              "url": "https://app.bigdata.com/documents/94D398DC4659EA44555D1422A878EB4F?cnum=1",
              "cnum": [
                1
              ],
              "timestamp": "2026-11-10T08:05:48"
            }
          ]
        }
      ],
      "usage": null
    }
  ],
  "simulation": {
    "phase": "completed",
    "runs_requested": 1,
    "runs_completed": 1
  }
}
```

## Practical Tips

### Leave out novelty for flash

Flash previews do not judge novelty, so leave `novel` out when showing their events. A full simulation includes events rejected as already seen, marked `novel: false`.

### Simulated runs are not alerts

When showing history, separate runs with `is_simulation: true`. They were replays and were not delivered.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.