Authentication

Before creating monitors or connecting data sources, you need a Datarist account. Datarist uses email-based authentication — no third-party SSO required on free plans.

API authentication

For programmatic access, Datarist uses bearer tokens. Generate an API key from Settings → API keys in your dashboard. All API keys are prefixed with dt_live_.

Overview

The monitor creation wizard is a five-step flow. Each step is independently editable after activation — you never need to delete and recreate a monitor to change a threshold or add a channel.

Interactive demo

This is a live replica of the actual monitor creation UI. Click through each step to see exactly what you'll encounter in the dashboard.

Step 1 — Data source

The first step asks you to name the monitor and select the connector type. The name appears in all alert notifications and your dashboard, so be descriptive. "Revenue crossed $50k" is better than "Monitor 3".

Supported connector types

SQL query requirements

For PostgreSQL and MySQL connectors, your query must return exactly one row with a column named value. Datarist reads this column and compares it against your condition thresholds.

Step 2 — Conditions

Conditions define the logic Datarist evaluates on each check run. Each condition compares a field value against a threshold using an operator. You can stack multiple conditions with AND or OR logic.

Condition structure

Each condition has three parts: a field path, an operator, and a threshold value.

Trigger modes

The trigger mode controls when alerts fire relative to your polling cycle:

Step 3 — Channels

Configure where Datarist sends the alert. All selected channels fire simultaneously — not sequentially. A failed SMS delivery will not delay or prevent email delivery.

Sample alert notifications

Message templates

Override the default message with a custom template using handlebars-style variables. Templates are per-monitor and apply to all channels unless overridden at the channel level.

Step 4 — Schedule

Control how often Datarist polls your source and how it behaves when the same condition fires repeatedly.

Check frequency

Deduplication

When dedup_enabled is true, Datarist suppresses repeat alerts for the same monitor within the configured cooldown window. This prevents alert fatigue when using every_match mode on a fast polling interval.

Auto-resolve

When auto_resolve is enabled, Datarist sends a recovery notification the first time a condition returns to false after having been true. Useful for incident-style monitoring where you want to know both when a problem starts and when it ends.

Step 5 — Review & activate

The review screen shows a complete summary of every configured value and a rendered sample notification message. Take a moment to verify the summary is correct — mismatched thresholds are the most common setup mistake.

Editing a monitor

You can edit any field of an active monitor without deleting and recreating it. Changes take effect on the next polling cycle after saving.

What can be edited

Editing via dashboard

Editing via API

Pausing & resuming

Pausing a monitor halts all polling and alert delivery without deleting any configuration. This is useful during planned maintenance windows or when you want to temporarily silence a noisy monitor.

Monitor states

Pausing via dashboard

Open the monitor detail page and click the Pause button in the top-right action bar. The monitor's status indicator turns gray immediately. All pending check runs are cancelled.

Pausing via API

Alert history

Every alert fired, suppressed, or failed is recorded in the monitor's alert history. History is retained for 90 days on all plans.

History log fields

Fetching history via API

PostgreSQL connector

The PostgreSQL connector allows Datarist to poll any PostgreSQL 12+ database. Datarist connects using a standard TCP connection and executes your configured SQL query on each check run.

Setup

Connection settings

MySQL connector

The MySQL connector supports MySQL 5.7+ and MariaDB 10.3+. Configuration mirrors the PostgreSQL connector — provide host, port, database, and credentials for a read-only user.

Setup

Connection settings

Google Sheets connector

Monitor values in a Google Sheets spreadsheet using a cell range. Datarist reads the specified range and treats the top-left cell's value as the monitored value.

Connecting your Google account

Webhooks connector

The Webhooks connector gives you a unique inbound URL. When your system posts JSON to this URL, Datarist evaluates the payload against your monitor's conditions in real-time — no polling required.

Setup

Select Webhook as the source type in the monitor wizard. Datarist generates a unique endpoint URL for that monitor. Configure your system to POST JSON to this URL when data changes.

JSON path configuration

In the monitor setup, specify the JSON path to the numeric field you want to monitor, e.g. revenue or metrics.active_users. Datarist extracts this field and evaluates it against your conditions.

Email channel

Datarist delivers alert emails via SendGrid. Emails arrive from alerts@datarist.io and include the monitor name, observed value, threshold, source, and a direct link to the monitor dashboard.

Configuration

Slack channel

Datarist posts alerts to Slack via an Incoming Webhook URL. You can configure a different Slack webhook per monitor, allowing you to route alerts to different channels based on severity or team.

Getting a Slack webhook URL

SMS channel

Datarist delivers SMS alerts via Twilio. SMS is available on Growth and Enterprise plans. Each alert message is capped at 160 characters; longer messages are truncated.

Configuration

Operators reference

Operators define the comparison logic between an observed value and a configured threshold. All operators are case-insensitive in the API.

Combining operators with logic modes

When a monitor has multiple conditions, the condition_logic field controls how they combine:

• all — every condition must be true (AND logic)
• any — at least one condition must be true (OR logic)

Templates reference

Message templates let you customize the content of alert notifications. Templates use double-brace variable syntax and are evaluated at alert fire time using the actual observed values.

Available variables

Example templates

REST API

The Datarist REST API allows full programmatic control over monitors, connectors, and alert history. The base URL is https://api.datarist.io/v1.

Endpoints

Create a monitor

Plan limits

Datarist enforces limits per plan across monitors, check frequency, and retention. Limits apply per organization workspace.

Troubleshooting

My monitor isn't firing

• Check the monitor status — it may be in draft or paused state.
• Navigate to the monitor's Check runs tab and inspect the last run's outcome and observed value.
• Verify your SQL query returns a row with a column named exactly value — not count, total, or anything else.
• If using on_crossing mode, confirm the condition was previously false. It will not re-fire while still true.
• Check if deduplication is suppressing the alert — look for suppressed status in the delivery log.

My source connection is failing

• Use the Test connection button on the connector page to validate credentials without creating a monitor.
• For PostgreSQL/MySQL: ensure Datarist's IP range is whitelisted in your database's firewall rules.
• Check the connector's last_error_msg field via GET /v1/connectors/{id} for the exact failure reason.

I'm getting too many alerts

• Switch trigger mode from every_match to on_crossing if you only need to know when the threshold is first breached.
• Increase the deduplication cooldown window from 1 hour to 4 hours or 24 hours.
• Reduce polling frequency — switching from 1 min to 5 min cuts check runs by 80% with minimal impact for most use cases.