> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toorow.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Operations & Connection Health
> What the platform knows about its own night — which connections are healthy, which steps ran, and what a crash leaves behind.
Two questions an operator asks every morning: *is anything broken upstream?* and
*did last night actually run?* toorow answers both from recorded facts, not from
the absence of an alert.
***
## Connection health
A connection carries a status, and a report is as healthy as its **worst** input
— never its first, and never its newest.
| Status | What it means |
| ----------------- | -------------------------------------------------------------------------------------- |
| `revoked` | The authorization is gone. Nothing will be pulled until it is granted again. |
| `provider_denied` | The provider refused this pull. The credential is valid; this request was not allowed. |
| `populate_failed` | The pull ran and could not land its rows. |
| `stale` | Nothing new has arrived for longer than the policy allows. |
| `ok` | Fresh, and pulling. |
Three rules make this readable rather than noisy:
* **The pull that learns writes.** A provider refusal is recorded by the pull
that hit it, inside its own transaction — not inferred later by a sweep.
* **A sweep never raises a red somebody else posted**, and only a pull that
verifiably succeeded clears one. A red does not decay into green because time
passed.
* **`provider_denied` leaves the door open.** Unlike `revoked`, it does not close
the enqueue gate: the daily probe is the detector of restoration, and a
verified `ok` pull lifts the red **without any console gesture**. A denial is
not a disablement.
The two reds are not the same fact either. `revoked` means the authorization
itself is dead and someone has to reconnect. `provider_denied` means the
authorization is alive — the token still refreshes — and the provider is refusing
the data this connection exists to collect.
***
## The night, step by step
The platform writes the list of steps **at dispatch, before the first one runs**.
That ordering is the whole design: a crash cannot erase a step it never got to
close, so an unfinished step stays visibly unfinished.
Four outcomes that cannot collapse into one another, plus one derived:
| Outcome | What it says |
| --------------- | ------------------------------------------------------------------------- |
| `never_started` | The step was declared and the run never reached it. |
| `unfinished` | It started and never closed — the crash *is* this line. |
| `failed` | It ran and reported a failure. |
| `succeeded` | It ran and finished. |
| *unrecorded* | Derived: no line at all, which means the dispatch itself never wrote one. |
“No alert” is therefore never the answer to *did it run?* — the absence of a
record is itself a state with a name.
***
## Where to look
A **clock** is one scheduled job. Reading one returns three things, never one:
the **declared** cadence (what the platform decided), the **observed** one (what
the scheduler is actually running), and the **drift verdict** between them —
`in_sync`, `drifted`, `missing_in_gcp`, `unmanaged_in_gcp` or `unknown`.
Drift is *rendered, never silently corrected*. And when the scheduler cannot be
observed at all — no credential, no network — every verdict is `unknown` and the
observation is marked unreachable. Never `in_sync`: an observation that did not
run proves no synchronisation.
| Endpoint | Method | Answers |
| ----------------------------------------- | -------------- | --------------------------------------------------------- |
| `/api/platform/clocks` | `GET` | Every clock: declared, observed, drift verdict. |
| `/api/platform/clocks/{clock_name}` | `GET`, `PATCH` | One clock, and editing its **declared** cadence. |
| `/api/platform/clocks/{clock_name}/apply` | `POST` | Pushes the declared clock into the scheduler. Idempotent. |
| `/api/platform/clocks/{clock_name}/run` | `POST` | Fires one clock immediately. |
| `/api/platform/nightly-steps` | `GET` | Last night's steps, each with its outcome and duration. |
The console shows the same model on **Platform Clocks** — the beats, and one
level below them, what the beat actually did. Both surfaces serialise the same
read model and neither reshapes it: two answers to *"is it in sync?"* would be
the same as none.
**There is no MCP tool for the nightly steps, and that is deliberate.** The
clock tools exist because a drift verdict is *configuration* an agent can act
on. The nightly steps are the platform's own execution history, and an agent
works inside a project: the question it actually has — *why is yesterday's data
missing?* — already has doors at the right scale (`datastream_diagnose`,
`datastream_pull_history`, `list_datastream_runs`), and the envelope it
receives already carries how stale the data is. Reading the platform's dispatch
to explain one project's data would be the opposite of the isolation the
product holds everywhere else.
***
## What an agent can ask
* `list_platform_clocks`, `get_platform_clock` — the beats and their cadence.
* `run_platform_clock_now`, `set_platform_clock_cadence`, `apply_platform_clock` —
changing when things happen.
* `get_connector_activation_status`, `get_connector_verification_status`,
`get_connector_installation_status` — is this connector installed, proved, and
pulling for this organization?
* `datastream_diagnose`, `datastream_pull_history`, `list_datastream_runs` — why
did this one stop, and what did it do before.
***
## Next Steps & Cross-References
The ten monitors that run once the rows have landed.
What a pull does, and what it records while doing it.
The operations profile, and what it takes to reach it.
Turning the scheduler on, and where it runs.