Set up a Monitor | Agent guide

Human guide: task steps and agent prompt → A Monitor receives supported provider events and writes accepted rows to the Database. A separate Play reacts through a stream listener. How Monitors work explains that boundary. Use an authenticated workspace. Define the source events and scope before deployment. Supported types and provider requirements determine available feeds.

1. Inspect supported types and existing coverage

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

While has_more is true, continue with --cursor <next_cursor>. Check every page before concluding that no existing Monitor covers the source. Inspect a candidate by its returned key:

MONITOR_KEY="existing-monitor-key"
deepline monitors get "$MONITOR_KEY" --json

Reuse an existing Monitor when its scope covers your events. Several Plays can consume the same stream. Types, payloads, output tables, and pricing depend on the workspace and provider.

2. Define the source scope

Save this example as monitor.json. It watches job openings at one company:

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

Replace the key and payload for your intended source. Inspect the selected type with deepline describe <monitor-tool-id> for its current payload schema. Scope the Monitor itself. For event-priced feeds, filtering in a Play does not reduce accepted events or their charges.

3. Validate and review the deployment plan

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

These commands validate without deploying, creating upstream resources, or spending credits. They do not prove source delivery or downstream Play execution. Resolve validation errors and existing-scope conflicts. Review the proposed scope and available Deepline pricing. An unavailable estimate does not mean zero cost. If check returns a preview hint, the type supports a paid source sample. An unavailable preview does not prevent deployment of a supported definition. Deployment dry runs remain separate from these paid samples.

Sample a new-hire feed before deployment (paid)

Current paid previews support deepline_native.company_radar with radar_type: "company_new_hires". Save this separate definition as new-hire-monitor.json:

{
  "key": "acme-new-hires",
  "tool": "deepline_native.company_radar",
  "payload": {
    "domain": "acme.com",
    "radar_type": "company_new_hires",
    "departments": ["Engineering"]
  }
}

Each returned match costs the same as a finding from the deployed feed. An empty preview is free. Choose and retain an idempotency key before requesting the sample:

deepline monitors preview --file new-hire-monitor.json --limit 2 \
  --idempotency-key acme-new-hires-sample-1 --json

Retry the same definition and limit with the same key to recover that sample without paying again. A new key requests a new paid preview. JSON mode requires an explicit key. Previews return up to three matches and create no Monitor. They can miss matches; an empty sample does not prove that the feed will find nothing. payload.updates_since is ignored for preview and still applies on deploy.

4. Deploy and inspect the result

deepline monitors deploy --file monitor.json
deepline monitors get acme-job-openings --json

Deployment activates the feed and can incur Deepline credits. Pricing can apply at deployment, reactivation, renewal, or per accepted event. deploy sets the complete definition for its key. Omitting a field can remove a filter or replace the upstream resource. Use monitors update for a patch. Confirm the state, scope, output stream, and Database table. Inspect connected Plays and their listener health. If an operation returns a Monitor Job ID, inspect it with deepline monitors jobs get <job-id>. A Monitor has five customer states:

State	Meaning
`provisioning`	Creation is accepted, but provider confirmation is pending. No events are stored or billed yet.
`active`	The Monitor is enabled for its configured feed.
`billing_suspended`	Billing owns the off state. See Billing suspension.
`errored`	The provider stopped the Monitor after it was created, for example because its LinkedIn URL no longer resolves. `failure.message` says what to do: update the payload, or delete the Monitor.
`disabled`	The Monitor is stopped for another reason, including an explicit customer stop.

An errored Monitor stays errored until its payload changes. Updating it with a new payload, such as the person’s current LinkedIn URL, creates a fresh Monitor resource and makes it active again. Resubmitting the same payload, starting it, or reactivating it leaves it errored. An active state does not prove that an event arrived or its Play succeeded. Check source delivery and consumer execution separately. For a pushed feed, monitors test validates a provider event against the deployed Monitor. It stores no row, spends no credits and starts no Play:

deepline monitors test acme-job-openings '{"field":"value"}'

Replace the illustrative JSON with that provider’s event fields.

5. Connect a Play to the stream

Save this as 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 listener runs for each matching row. Keep its tool and stream aligned with the Monitor. Use where to select rows; put joins and business decisions in the Play body.

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

After publishing, inspect the listener and its result when a matching row arrives. This pushed feed needs no manual Monitor run or polling job.

Deploy Monitor files from Git

Repository-owned Monitor definitions

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.Applied provider changes remain live 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-owner notifications are enabled by default when Monitors are turned off. Configured delivery settings and recipient preferences determine delivery. Eligible credit- and cap-suspended Monitors come back through the normal lifecycle after the restriction clears and upstream cleanup completes: 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. Customer-stopped Monitors and opaque billing failures are not automatically reactivated. 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

Verify deletion and any returned Monitor Job before assuming the provider resource is gone. See the Monitor contract reference for payloads, streams, pricing, and update semantics. Continue with Process Monitor events for an end-to-end hiring signal. Use Database for retained data and CRM outcomes.

Start here

Building Your Own Plays

Migrations

Find and enrich data

Qualify and route leads

Manage CRM and accounts

Campaigns and outreach

Work with data

Integrate Plays