Monitors

A monitor looks for signals on a schedule. The V2 API creates organization-owned monitors through POST /monitors or the compatible campaign-nested route. Its config says what to watch and which signal types to look for. Each scheduled run of a monitor is a run of kind monitor, and the run can create signals. To move a V1 integration, read Migrate from V1.

A source campaign is required only for signal-sheet. A topic monitor needs no source campaign or existing records. Monitor targets and signal subjects explains independent monitors and retained signals in this candidate.

The monitor object

{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "campaign_id": "3f2b8a4e-1c5d-4e7f-9a0b-6c2d8e1f4a7b",
  "name": "Funding rounds",
  "config": {
    "type": "signal-topic",
    "signal_types": [
      {
        "type": "funding",
        "display": "Funding",
        "description": "Investment rounds and capital raises"
      }
    ],
    "entity_type": "company",
    "webhook_url": null,
    "topic_criteria": "Data integration companies that raise a Series A",
    "geographic_filters": null,
    "industry_filters": null,
    "company_size_filters": null
  },
  "frequency": "weekly",
  "status": "active",
  "next_run_at": "2026-09-30T12:00:00.000Z"
}

Config types

config.type selects what the monitor watches. The type cannot change after create.

The V2 API cannot create the file_id of a signal-csv monitor. To watch the records of a CSV file, import the file with upload_import, then create a signal-sheet monitor for the campaign.

Every config type also has these fields:

entity_filters limits the records that a signal-sheet monitor watches. Null watches every record.

• Each key is status or the path of a data field, for example data.industry.value. status matches the stored review state. A record with no stored state reads new. To match new records, send {"status": {"$in": ["new", null]}}. Older records can store contacted, which the V2 API shows as reviewed. To match every record that reads reviewed, send {"status": {"$in": ["reviewed", "contacted"]}}.
• Each value is a JSON scalar, which the field must equal, or an object of operators.
• $eq, $ne, $gt, $gte, $lt and $lte take a scalar.
• $in and $nin take a list of scalars.
• $exists takes true or false.
• $regex takes a pattern of at most 200 characters. Start the pattern with (?i) to ignore case.
• Other fields, other operators and top-level operators such as $or or $where give 422.

Frequency and status

• When the monitor is active, the first run starts at next_run_at. A paused monitor has a null next_run_at. create_monitor does not start a run at once. run_monitor starts one run now. The schedule does not change.
• Each run of a monitor has kind monitor and the monitor_id of the monitor. result.completed is the number of signals that the run processed. Read Runs.
• A scheduled run needs credits. A run that cannot start for lack of credits gets the status skipped.
• Send status paused to stop the scheduled runs. Send active to start them again.

Webhook URL

config.webhook_url is a URL that gets a notification when a run of the monitor ends. config.format selects the payload: legacy (the default) or v2. This section describes the legacy format. V2 webhooks describes the signed v2 format and its verification secret. There is no event subscription. Discovery, import and export runs have no webhook setting in the V2 API.

Signal routes a notification to the currently configured webhook of the monitor that started the run. Signal skips delivery when it cannot confirm that monitor. Notification payload IDs are not guaranteed to be V2 IDs.

Treat the notification as a prompt to read data through the API. Call get_run or list_runs for the run status. To read the new signals of a run, call list_signals with the monitor_id of the run and created_after set to the started_at of the run.

To set or clear the URL, send config.webhook_url to update_monitor. Send null to clear it.

Roles and changes

Monitor operations use resource permissions. Organization roles do not replace them. See Permissions.

• Reading needs monitor.read. Listing monitors through a campaign also needs campaign.read.

• Creation needs monitor.write and schedule.write. An active schedule also needs run.write. Campaign-linked creation needs campaign access, and each source needs its own reads.

• Updating needs monitor.write. Changing frequency or status also needs schedule.write, plus campaign.write for a campaign-linked monitor. Enabling recurring execution needs run.write.

• Setting or clearing the webhook URL needs webhook.write.

• run_monitor needs monitor.read, run.write, and the permissions of its execution inputs and effects.

• Deletion needs monitor.write and schedule.write. Canceling queued or running work also needs run.write.

• update_monitor changes only the fields in the body. A config change must use fields of the current config type.

• update_monitor gives 409 when you send config for a monitor with a null config. It also gives 409 when you send status active for a monitor with a null campaign_id and no schedule.

• delete_monitor deletes the monitor, its schedule and the signals that it found. It cancels the active runs of the monitor. After the delete, get_run and list_runs do not find the runs of the monitor. You cannot undo the delete.

Operations

Each path below follows $LINKT_API_URL/v2. Set LINKT_API_URL to the origin only, for example https://api.signal.linkt.ai.

The next example creates a paused monitor. A paused monitor starts no run and uses no credits. Send status active to start the schedule. Each scheduled run uses credits.

curl --fail-with-body --request POST "$LINKT_API_URL/v2/campaigns/$CAMPAIGN_ID/monitors" \
  --header "x-api-key: $LINKT_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$(jq -cn --arg CAMPAIGN_ID "$CAMPAIGN_ID" '{"config":{"signal_types":[{"description":"A new funding round or a new investment.","display":"Funding","type":"funding"},{"description":"A new executive in data, IT, or engineering.","display":"Leadership change","type":"leadership_change"}],"source_campaign_id":"0190a4e2-0000-7000-8000-000000000001","type":"signal-sheet"},"frequency":"weekly","name":"Funding and leadership changes","status":"paused"} | walk(if . == "0190a4e2-0000-7000-8000-000000000001" then $CAMPAIGN_ID else . end)')"

curl --fail-with-body --request GET "$LINKT_API_URL/v2/campaigns/$CAMPAIGN_ID/monitors?limit=5" \
  --header "x-api-key: $LINKT_API_KEY"

Related

• Monitor accounts for signals
• Signals
• Runs
• API reference

Monitor create and update reject unknown fields inside each signal_types item with 422 validation_error. Each item accepts type, display and description. The validation details identify the unknown field with extra_forbidden.