Quickstart | Tidewater docs

This guide takes you from nothing to a working alert. You will register a pipeline, report one run, tell Tidewater when the data should arrive and then let that time pass.

1. Install the client

Use the client for your language, or skip it and call the API directly with curl. All three examples below do the same thing.

Python

pip install tidewater

TypeScript

npm install @tidewater/client

curl

curl --version   # nothing to install

2. Register a pipeline

A pipeline is one job or stream that produces data. Register the one you care about most. The assets list names the tables it writes, so lineage and impact work from the start.

Python

import os
from tidewater import Client

tw = Client(token=os.environ["TIDEWATER_TOKEN"])

pipeline = tw.pipelines.create(
name="orders_daily",
source="airflow",
owner="finance-data",
assets=["analytics.orders", "analytics.daily_revenue"],
)
print(pipeline.id) # pl_8f2k1

TypeScript

import { Tidewater } from '@tidewater/client';

const tw = new Tidewater({ token: process.env.TIDEWATER_TOKEN! });

const pipeline = await tw.pipelines.create({
name: 'orders_daily',
source: 'airflow',
owner: 'finance-data',
assets: ['analytics.orders', 'analytics.daily_revenue'],
});
console.log(pipeline.id); // pl_8f2k1

curl

curl -s https://api.tidewater.example/v1/pipelines \
-H "Authorization: Bearer $TIDEWATER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "orders_daily",
"source": "airflow",
"owner": "finance-data",
"assets": ["analytics.orders", "analytics.daily_revenue"]
}'

3. Report a run

When your job finishes, tell Tidewater. The run_key is yours to choose. Using the logical date means a retry updates the same run instead of creating a second one.

Python

tw.runs.report(
  pipeline_id="pl_8f2k1",
  run_key="2026-10-24T04:00:00Z",
  status="succeeded",
  started_at="2026-10-24T04:00:12Z",
  finished_at="2026-10-24T04:07:41Z",
  rows_written=1_284_031,
)

TypeScript

await tw.runs.report('pl_8f2k1', {
runKey: '2026-10-24T04:00:00Z',
status: 'succeeded',
startedAt: '2026-10-24T04:00:12Z',
finishedAt: '2026-10-24T04:07:41Z',
rowsWritten: 1_284_031,
});

curl

curl -s https://api.tidewater.example/v1/pipelines/pl_8f2k1/runs \
-H "Authorization: Bearer $TIDEWATER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "run_key": "2026-10-24T04:00:00Z",
  "status": "succeeded",
  "started_at": "2026-10-24T04:00:12Z",
  "finished_at": "2026-10-24T04:07:41Z",
  "rows_written": 1284031
}'

4. Say when the data should arrive

Set a freshness expectation: the time by which the data should be current, in the time zone your readers use.

Python

tw.expectations.set(
  pipeline_id="pl_8f2k1",
  freshness={
      "deadline": "06:00",
      "timezone": "America/New_York",
      "days": ["mon", "tue", "wed", "thu", "fri"],
  },
  volume={"min_rows": 900_000},
)

TypeScript

await tw.expectations.set('pl_8f2k1', {
freshness: {
  deadline: '06:00',
  timezone: 'America/New_York',
  days: ['mon', 'tue', 'wed', 'thu', 'fri'],
},
volume: { minRows: 900_000 },
});

curl

curl -s -X PUT https://api.tidewater.example/v1/pipelines/pl_8f2k1/expectations \
-H "Authorization: Bearer $TIDEWATER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "freshness": {
    "deadline": "06:00",
    "timezone": "America/New_York",
    "days": ["mon", "tue", "wed", "thu", "fri"]
  },
  "volume": { "min_rows": 900000 }
}'

5. Choose where alerts go

In the app, open Alerts, then Channels, and connect Slack, Microsoft Teams or an e-mail address. Then create a rule that sends late data alerts to the owner of the pipeline. The default rule already does this for the owner you set in step 2.

6. See an alert

The quickest way to see an alert is to skip a run. Do not report anything for orders_daily and wait for 06:00 in the time zone you chose. Tidewater opens an alert as soon as the deadline passes without current data, and it lists what is affected.

What to do next

Read concepts to learn how Tidewater decides that data is late.
Connect your orchestrator and warehouse so runs and lineage appear without code.
Set owners for your ten most important tables, then add a rule for each owning team.