Set up a Monitor

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 with Monitor access. Know which source events you want to accept and the smallest scope that produces useful data.

1. Check access and inspect supported types

deepline monitors status --json
deepline tools list --categories monitors
deepline tools 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 --status all --json
MONITOR_KEY="acme-job-openings" # Replace with a key returned by the list.
deepline monitors get "$MONITOR_KEY" --json

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 tools describe deepline_native.company_radar --json. 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.

5. Confirm the live Monitor

deepline monitors get acme-job-openings --json

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.

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 { definePlay } from 'deepline';
import type { SqlListenerEvent } from 'deepline';

export default definePlay(
  'on-job-opening',
  async (ctx, event: SqlListenerEvent<Record<string, unknown>>) => {
    const row = event.after; // null for DELETE
    if (!row) return { handled: false };
    const captured = await ctx.dataset('monitor_events', [row]).run();
    return { handled: true, capturedRows: await captured.count() };
  },
  {
    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'],
      },
    ],
  },
);

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.

Change or remove 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 --json
deepline monitors delete acme-job-openings --dry-run

Delete only after reviewing the plan. The actual deletion command deprovisions the upstream provider resource:

deepline monitors delete acme-job-openings --yes

How Monitors work

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

Where data lives

Decide when an event belongs in the Database and when an outcome belongs in a CRM.

Monitor contract reference

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

Get started

Build and automate

Common workflows

Data and integrations

Reference

Before you start

1. Check access and 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

Change or remove a Monitor safely

How Monitors work

Where data lives

Monitor contract reference

​Before you start

​1. Check access and 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

​Change or remove a Monitor safely

How Monitors work

Where data lives

Monitor contract reference

Before you start

1. Check access and 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

Change or remove a Monitor safely