Set up a Monitor - Deepline

Deploy one scoped supported feed and verify its stream and consumer independently.

Use this guide to deploy a scoped provider event feed. A Monitor receives events pushed into Deepline by a supported external source and writes accepted rows to the Database. A Play is separate: it runs code when a matching row reaches a stream.

A Monitor accepts data. It does not contain the code that reacts to it. Read How Monitors work for the product model.

Before you start

You need an authenticated Deepline workspace. Know which source events you want to accept and the smallest scope that produces useful data.

1. Inspect supported types

deepline tools list --categories monitors
deepline describe deepline_native.company_radar --json

The list returns the Monitor tool IDs available to your workspace. Replace deepline_native.company_radar with one of those IDs, then use its returned payload schema. Available Monitor types, streams, output tables, and pricing depend on your workspace and the provider. If the source might already be covered, inspect the existing registry before you deploy another feed:

deepline monitors list --state all
MONITOR_KEY="acme-job-openings" # Replace with a key returned by the list.
deepline monitors get "$MONITOR_KEY" --json

The list is paginated. When the response reports has_more: true, run it again with --cursor <next_cursor> before you conclude that no existing Monitor covers your scope. One Monitor can supply a stream to several Plays. Reuse a Monitor when its existing scope already covers the events you need.

2. Define the narrowest useful scope

Save a definition as monitor.json. This example watches job openings at one company through the Deepline Native company radar:

{
  "key": "acme-job-openings",
  "tool": "deepline_native.company_radar",
  "payload": {
    "domain": "acme.com",
    "radar_type": "company_job_openings"
  }
}

Replace the key and payload with the schema returned by deepline describe deepline_native.company_radar. Scope the Monitor itself rather than accepting a broad feed and filtering only in a Play. For an event-priced Monitor, a Play filter does not reduce the events the Monitor accepts.

3. Validate without deploying or spending credits

deepline monitors check --file monitor.json

check validates the definition. It does not deploy a Monitor, create an upstream resource, or spend credits. Resolve every validation error before you continue.

4. Preview the deployment, then deploy

deepline monitors deploy --dry-run --file monitor.json

The dry run shows the deployment plan, including available price information and any existing Monitor that may already cover the scope. It does not deploy or change upstream resources. If the scope and price are right, deploy the definition:

deepline monitors deploy --file monitor.json

This is the step that activates the provider event feed. Monitor pricing can apply at deployment or reactivation, per accepted event, or at renewal. The CLI shows Deepline credits, not provider spend. deploy sets the complete definition for its key. Deploying again with a field left out removes that field and can replace the upstream resource. To change one field, use deepline monitors update instead.

5. Confirm the live Monitor

deepline monitors get acme-job-openings

Confirm the Monitor is active, its output stream and Database table match the intended data, and its scope has not widened. The response also shows connected Plays and their current listener health when available. A Monitor is always in one of four states:

State	Meaning
`provisioning`	Deepline accepted the Monitor and is waiting for the provider to confirm it. It stores no events and is not billed yet.
`active`	The Monitor is receiving events from its provider.
`billing_suspended`	Billing turned the Monitor off. See Billing suspension.
`disabled`	The Monitor was turned off for any other reason, including `stop`.

For a source that pushes events to Deepline, you can check a sample event against the deployed Monitor without storing a row, spending credits, or starting a Play:

deepline monitors test my-monitor '{"field":"value"}'

Pass the provider’s event fields as the JSON object.

6. Connect a Play to the stream

Write a Play with a sqlListeners trigger for the Monitor’s exact tool and stream, for example on-job-opening.play.ts:

import deepline from 'deepline';
import type { SqlListenerEvent } from 'deepline';

export const config = {
  description: 'Run whenever the Monitor writes a new job opening row.',
  sqlListeners: [
    {
      id: 'events',
      tool: 'deepline_native.company_radar',
      stream: 'company_job_openings',
      operations: ['INSERT'],
    },
  ],
};

export default async function (
  event: SqlListenerEvent<Record<string, unknown>>,
) {
  const row = event.after; // null for DELETE
  if (!row) return { handled: false };
  const captured = await deepline.dataset('monitor_events', [row]).run();
  return { handled: true, capturedRows: await captured.count() };
}

The Play wakes on each matching row. Keep the tool and stream aligned with the Monitor, then narrow its where filter to the rows that should run code. Put joins and business decisions in the Play body, not in the Monitor definition. Check and publish the Play when its logic is ready:

deepline plays check on-job-opening.play.ts
deepline plays publish on-job-opening.play.ts

After publishing, a matching Database row starts the Play. There is no polling job or manual Monitor run.

Deploy Monitor files from Git

Commit the same JSON definition as monitors/acme-jobs.monitor.json. Linked repository deployments discover **/*.monitor.json by default, even when deepline.json is absent. Set monitors in deepline.json to narrow or replace that glob:

{
  "plays": ["plays/**/*.play.ts"],
  "monitors": ["monitors/**/*.monitor.json"]
}

Globs are relative to the linked project’s root directory. Setting "monitors": [] disables file discovery. Pull requests validate the definitions and show proposed changes and available Deepline pricing without provisioning Monitors. A push to the production branch applies changes and waits for the Monitor Jobs to finish. Usual Monitor pricing and workspace access requirements apply. Stopped Monitors stay stopped when you push. Deleting a file, narrowing the globs, or setting "monitors": [] leaves existing Monitors unchanged. Remove a live Monitor explicitly using the commands below. Provider changes are not rolled back if a later step fails. Inspect deepline git deployments <id> and the affected Monitors before retrying.

Monitor many rows from a table (beta)

A Fleet keeps one Monitor for each selected row of a Database table, such as one company radar per target account. Each member is an ordinary Monitor with its usual pricing; a Fleet adds no fee of its own.

deepline monitors fleets init account-job-openings \
  --source public.accounts --key account_id --key-type uuid \
  --tool deepline_native.company_radar \
  --payload '{"domain":"{{domain}}","radar_type":"company_job_openings"}' \
  --order-by intent_score:desc \
  --out fleet.json
deepline monitors fleets deploy --file fleet.json --dry-run
deepline monitors fleets deploy --file fleet.json --wait
deepline monitors fleets get account-job-openings

{{domain}} is filled from each source row. The dry run shows the plan and the Deepline credits due before anything changes. A Fleet holds up to 1,000 active members and checks its source table about once a minute. Membership is sticky: a higher-ranked row fills an open slot but does not replace a current member. A member whose row leaves the table is turned off after 7 days. Run deepline monitors fleets --help for the complete lifecycle, including deactivate and reactivate.

Change a Monitor safely

Inspect the Monitor and its connected Plays before changing it. Its output stream can also feed queries, dashboards, exports, or warehouse jobs.

deepline monitors get acme-job-openings

To change part of the definition, send only the fields you want to change. Payload fields are merged with the stored payload:

deepline monitors update acme-job-openings '{"payload":{"job_titles":"\"VP Sales\" OR \"CRO\""}}'

A Deepline Native radar starts from new events unless you set payload.updates_since, which requests historical events from that time. Changing only filters, or restarting a Monitor, does not replay the period it was off.

Pause and resume a Monitor

stop turns the Monitor off upstream and keeps its definition. start applies that saved definition again and can charge reactivation pricing. Preview either with --dry-run:

deepline monitors stop acme-job-openings --dry-run
deepline monitors stop acme-job-openings
deepline monitors start acme-job-openings --dry-run
deepline monitors start acme-job-openings

Both commands return a Monitor Job. Run deepline monitors jobs wait <job-id> to wait until the provider has made the change. A Monitor you stop stays stopped, including when you add credits, change the spending cap, or push its file from Git.

Billing suspension

Deepline turns off every Monitor in the workspace and marks it billing_suspended when either of these happens:

Any spend, from a Monitor, Play, or tool, takes the credit balance below 0 and no automatic recharge is in progress.
Spend this billing period reaches the workspace’s monthly spending cap.

A monthly-billed Monitor keeps running until the end of the period it already paid for. A Fleet member is the exception: it turns off with its Fleet, and recreating it inside that period costs nothing extra. Workspace owners get an email when Monitors are turned off. Monitors come back on their own once the workspace can pay again: after a top-up brings the balance above 0, or once spend is back under the cap because you raised it or older spend left the billing window. Events that arrive while a Monitor is off are not delivered or charged, and they are not replayed when it comes back. To check what is suspended, or to bring a Monitor back yourself after resolving a different billing problem:

deepline monitors list --state billing_suspended
deepline monitors reactivate acme-job-openings --dry-run
deepline monitors reactivate acme-job-openings

The dry run shows the reactivation cost in Deepline credits.

Remove a Monitor

deepline monitors delete acme-job-openings --dry-run

Delete only after reviewing the plan. The actual deletion command deprovisions the upstream provider resource. A deleted Monitor cannot be restarted; deploy a new one instead.

deepline monitors delete acme-job-openings --yes

How Monitors work

Understand the event path and the boundary between a Monitor and a Play.

From a Monitor signal to a Play

Follow one hiring signal from a scoped Monitor to a published Play.

Monitor contract reference

Inspect supported Monitor payloads, streams, outputs, and update semantics.

Verify this task

Check access, validate, and review the deployment preview before provisioning. Inspect Monitor state, Job outcome, and the listener’s tool/stream binding. Ask your agent to explain a failed check before repeating work or expanding the scope.

​Before you start

​1. Inspect supported types

​2. Define the narrowest useful scope

​3. Validate without deploying or spending credits

​4. Preview the deployment, then deploy

​5. Confirm the live Monitor

​6. Connect a Play to the stream

​Deploy Monitor files from Git

​Monitor many rows from a table (beta)

​Change a Monitor safely

​Pause and resume a Monitor

​Billing suspension

​Remove a Monitor

How Monitors work

From a Monitor signal to a Play

Monitor contract reference

​Verify this task

Before you start

1. Inspect supported types

2. Define the narrowest useful scope

3. Validate without deploying or spending credits

4. Preview the deployment, then deploy

5. Confirm the live Monitor

6. Connect a Play to the stream

Deploy Monitor files from Git

Monitor many rows from a table (beta)

Change a Monitor safely

Pause and resume a Monitor

Billing suspension

Remove a Monitor

Verify this task