> ## 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.
# Get started with Monitors
> Turn a Bigdata Search into a recurring feed of structured, source-backed events.
**Interested in Monitors?** The API is coming soon. To request early access or tell us about a monitoring use case, email [support@bigdata.com](mailto:support@bigdata.com).
Monitors turn a Bigdata Search into a recurring feed of structured events. Describe what you want to track, choose how often to search, and define the information you want returned. Each event links back to the source content.
You can test a monitor against recent historical data before turning it on. This lets you check the search results, extracted fields, and duplicate detection immediately instead of waiting for new content to arrive.
## How Monitors work
Save a search, a schedule, and the fields you want to extract. New monitors should start as `inactive` so they cannot produce scheduled results before you test them.
Run a simulation over recent data. The simulation uses the same configuration as the live monitor but does not activate it.
Check the results and their source links. Refine the search or extraction instructions if important developments are missing or irrelevant ones appear.
Change the monitor's status to `active`. Bigdata then evaluates it automatically at the frequency you selected.
Retrieve completed runs and send their structured events to your application, alerting system, or research workflow.
Test before activating. A short simulation makes it much easier to spot a search that is too broad, missing results, or extracting the wrong information.
## Create your first monitor
This example watches for credit rating downgrades and negative watch placements affecting BlackRock. It is inactive when created and will run once per hour after activation.
Only `intent` and `schedule` are required to create a monitor. The remaining fields let you customize its search and output:
* `name`: a short label that helps you recognize the monitor
* `intent`: what counts as a relevant event; this cannot be changed after creation
* `status`: whether the monitor is active or inactive
* `search_queries`: the search mode and [Search documents query](/api-reference/search/search-documents#body-query) to use for each run
* `schedule`: how often an active monitor searches
* `structured_output`: the fields returned with each event
* `extraction_instructions`: what to include and exclude
* `entity_watchlist`: the companies or other entities to track
```bash theme={null}
curl --request POST \
--url https://api.bigdata.com/v1/search-monitoring/monitors \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ' \
--data '{
"name": "Credit Rating Downgrade or Negative Watch",
"intent": "Watch for rating downgrades and negative watch placements affecting BlackRock",
"status": "inactive",
"search_queries": {
"search_mode": "fast",
"query": {
"text": "credit rating downgrade negative watch",
"max_chunks": 100
}
},
"schedule": {
"frequency": "1h"
},
"structured_output": {
"company": {
"description": "The company affected by the rating action.",
"field_type": "entity_reference"
},
"rating_agency": {
"description": "The credit rating agency announcing the action.",
"field_type": "text"
},
"action": {
"description": "The announced credit rating action.",
"field_type": "enum",
"values": [
"downgrade",
"negative_watch"
]
},
"new_rating": {
"description": "The new rating, when stated.",
"field_type": "text"
}
},
"extraction_instructions": "Only return a new event when a rating agency announces a downgrade or places the company on negative watch. Do not treat analyst recommendations as credit rating actions.",
"entity_watchlist": [
{
"name": "BlackRock Inc.",
"rp_entity_id": "HJ95FV"
}
]
}'
```
The response includes the new monitor in `data`. Save `data.id`; you will use it to test, update, and retrieve the monitor.
The watchlist uses Bigdata entity IDs. Use the [Knowledge Graph API](/api-reference/companies/find-by-details) to find the ID for each company you want to track.
## Test the monitor
A simulation tests the monitor without turning it on. In this example, the monitor runs over six consecutive one-hour periods ending at noon UTC on August 27, 2026.
```bash theme={null}
curl --request POST \
--url 'https://api.bigdata.com/v1/search-monitoring/monitors//simulate?end_timestamp=2026-08-27T12:00:00Z&number_of_runs=6' \
--header 'X-API-KEY: '
```
`end_timestamp` must be in UTC and at least five minutes in the past. `number_of_runs` is the number of periods to test, based on the monitor's frequency.
The API returns `202 Accepted` because the simulation continues in the background. Save the returned `simulation_id`, then use it to check the results:
```bash theme={null}
curl --request GET \
--url 'https://api.bigdata.com/v1/search-monitoring/monitors//runs?type=simulation&simulation_id=&include_events=true' \
--header 'X-API-KEY: '
```
Each run reports a status:
* `PENDING`: still processing
* `COMPLETED`: ready to review
* `FAILED`: could not be completed
## Start continuous monitoring
When the simulation produces the events you expect, turn on the monitor by changing its status:
```bash theme={null}
curl --request PATCH \
--url https://api.bigdata.com/v1/search-monitoring/monitors/ \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ' \
--data '{
"status": "active"
}'
```
To pause future runs without losing the configuration, change the status back to `inactive`.
## Key concepts
### Monitor
A monitor combines a saved search, extraction instructions, an output format, and a schedule. An active monitor evaluates newly available content automatically.
### Simulation
A simulation tests the monitor against historical data without activating it. Use simulations to improve the quality of your results before sending them into a live workflow.
### Run
A run is one evaluation period. For an hourly monitor, each run searches one hour of newly available content. Runs can come from an active monitor or a simulation.
### Event
An event is a relevant development extracted during a run. It contains a summary, your structured fields, and links to the source content that supports it.
In API responses, events appear in the `events` array.
### Search query
Monitors use the same [`query` object as Search documents](/api-reference/search/search-documents#body-query). This includes search text, filters, external search, chunk limits, and ranking settings, so you do not need to learn a separate query format.
The monitor adds the correct time period automatically, so do not use a fixed timestamp filter.
### Structured output
The structured output describes the fields returned for every event:
* `text` stores names, labels, and short details.
* `number` stores numeric values.
* `enum` limits a field to a predefined set of values.
* `entity_reference` links a company or other entity to the Bigdata knowledge graph.
Only add fields that your application needs to filter, compare, or route. The event summary and source links provide the supporting detail.
## What you can monitor
Once the first monitor is working, the same workflow can support:
Track announced acquisitions, divestitures, bids, and material deal-status changes.
Capture rate decisions and changes in forward guidance from major central banks.
Detect confirmed departures, retirements, and leadership transitions.
Watch for investigations, enforcement actions, judgments, and settlements.
Identify announced workforce reductions and major operating restructurings.
Follow commercially relevant AI launches, releases, and availability changes.