> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring Status

> One org-level snapshot of watch health, per-office pipeline freshness, and end-to-end pipeline verification

## Overview

A single, read-only snapshot of your whole monitoring program. It answers two different
questions in one response:

* **How are my watches doing?** The `watches` block is a rollup of every watch in your
  organization, counted by health state. It is scoped strictly to your org.
* **How fresh is Signa's data for each office?** The `offices[]` block is Signa's global
  per-office ingestion freshness. It is the same for every organization, computed once and
  shared through a 60 second cache, and it is not filtered to the offices your watches cover.

A third block, `pipeline`, carries the continuous end-to-end verification gauges. Every
timestamp in it is null-honest: a missing or stale check is reported as `null`, never as an
old value dressed up as a fresh verification.

Requires the `portfolios:manage` scope. Calling it never changes anything.

<Note>
  **`slo_hours` is an internal freshness target, not an SLA.** Each office carries an
  `slo_hours` value derived from that office's `update_cadence`. It is the ceiling Signa uses to
  decide `pipeline_status`: coverage within `slo_hours` is `ok`, coverage older than that (or no
  coverage signal at all) is `lagging`. It is an operational default that Signa can tune as an
  office's publishing behaviour changes. It is not a published service level and not a
  contractual commitment.
</Note>

## Query Parameters

None. The response is always the full snapshot.

## How to use it

**Gate a "no conflicts" report.** Before you tell a client that a watch surfaced nothing,
check that every office the watch covers reports `pipeline_status: "ok"`. A `lagging` office
means the register data behind that negative result is older than Signa's own freshness
target, so the report should say so or wait.

**Drive a dashboard tile.** The response is one call, small, and safe to poll. Show
`watches.by_health` as a status strip and `offices[]` as a freshness table. Because
`offices[]` is global, you can cache it across users and orgs.

**Run your own alerting.** Poll on a schedule and alert when `watches.by_health.degraded > 0`,
when an office you rely on flips to `lagging`, or when `pipeline.last_verified_end_to_end_at`
turns `null`. This is the same signal the dashboard Monitoring page reads.

For the meaning of each health state and the reasoning behind the null-honest gauges, read the
[Monitoring status guide](/guides/monitoring/monitoring-status).

## Response

<ResponseField name="object" type="string">Always `monitoring_status`.</ResponseField>

<ResponseField name="watches" type="object">
  Org-scoped aggregate over all of your non-deleted watches.

  <Expandable title="watches">
    <ResponseField name="total" type="integer">Count of your non-deleted watches.</ResponseField>

    <ResponseField name="by_health" type="object">
      Count of watches in each health state. All six keys are always present; a state with no
      watches reports `0`.

      <Expandable title="by_health">
        <ResponseField name="healthy" type="integer">Every in-scope office is evaluated and current.</ResponseField>
        <ResponseField name="lagging" type="integer">Coverage has stopped advancing beyond the expected window (office ingestion behind, or an evaluation backlog). Usually resolves on its own.</ResponseField>
        <ResponseField name="degraded" type="integer">The watch itself needs attention: repeated evaluation errors, or an entity filter that no longer resolves.</ResponseField>
        <ResponseField name="paused" type="integer">Paused by you. No new evaluation happens.</ResponseField>
        <ResponseField name="pending" type="integer">Active but not yet evaluated, still within the office refresh window.</ResponseField>
        <ResponseField name="unsupported" type="integer">The scope includes an office Signa does not yet ingest.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="offices" type="object[]">
  Global per-office pipeline status, one entry per live office. Not org-specific: identical for
  every organization, computed once and shared through a 60 second cache.

  <Expandable title="offices[]">
    <ResponseField name="office_code" type="string">WIPO ST.3 office code, uppercase (`US`, `EM`).</ResponseField>

    <ResponseField name="pipeline_status" type="'ok' | 'lagging'">
      `ok` when `coverage_through` is within `slo_hours` of now. `lagging` when coverage is
      older than that, or when there is no coverage signal at all.
    </ResponseField>

    <ResponseField name="coverage_through" type="string | null">
      Office-data time through which Signa has processed this office. This is source data time,
      never wall-clock. `null` when no eligible run carries a coverage signal.
    </ResponseField>

    <ResponseField name="last_completed_sync_at" type="string | null">
      Newest completed pull from the office, regardless of whether it is indexed yet.
    </ResponseField>

    <ResponseField name="last_search_indexed_at" type="string | null">
      When the latest eligible run for this office became searchable.
    </ResponseField>

    <ResponseField name="slo_hours" type="integer">
      Internal freshness ceiling in hours, derived from the office cadence. This is the number
      `pipeline_status` is measured against. Not a published SLA.
    </ResponseField>

    <ResponseField name="declined_runs_unresolved" type="integer">
      Sync runs for this office in the last 30 days that exceeded the evaluator's per-run change
      budget, were declined without evaluation, and have no audited re-drive recorded. Ingestion
      still happened, so `coverage_through` can look healthy; a non-zero value means changes
      from those runs were not evaluated against any watch. The affected windows appear as
      `budget_declined` gaps in [attestations](/api-reference/monitoring/watches/attestation).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pipeline" type="object">
  Continuous pipeline-verification gauges. Both timestamps follow one rule: a stale value is
  never presented as a fresh verification.

  <Expandable title="pipeline">
    <ResponseField name="last_verified_end_to_end_at" type="string | null">
      When a synthetic change last passed through the live pipeline end to end. `null` when no
      check has been recorded or the most recent one is older than the freshness horizon.
    </ResponseField>

    <ResponseField name="last_real_record_alert_at" type="string | null">
      When the representative real-record path last saw an office-originated change. A
      separate, slower signal than the synthetic heartbeat. Same null rule.
    </ResponseField>

    <ResponseField name="verification" type="'canary'">The mechanism behind the timestamps.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="request_id" type="string">Request identifier for support.</ResponseField>

## Errors

| Status | `type`      | When                             |
| ------ | ----------- | -------------------------------- |
| 403    | `forbidden` | Caller lacks `portfolios:manage` |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/monitoring/status" \
    -H "Authorization: Bearer sig_YOUR_KEY"
  ```

  ```typescript TypeScript theme={null}
  // The SDK does not wrap this endpoint yet; call it directly.
  const res = await fetch("https://api.signa.so/v1/monitoring/status", {
    headers: { Authorization: `Bearer ${process.env.SIGNA_API_KEY}` },
  });
  const status = await res.json();

  if (status.watches.by_health.degraded > 0) {
    notifyOps(`${status.watches.by_health.degraded} watches degraded`);
  }

  const lagging = status.offices.filter((o) => o.pipeline_status === "lagging");
  for (const office of lagging) {
    console.log(office.office_code, "coverage through", office.coverage_through);
  }
  ```
</CodeGroup>

<ResponseExample>
  ```json Healthy program with one lagging office theme={null}
  {
    "object": "monitoring_status",
    "watches": {
      "total": 412,
      "by_health": {
        "healthy": 401,
        "lagging": 6,
        "degraded": 2,
        "paused": 3,
        "pending": 0,
        "unsupported": 0
      }
    },
    "offices": [
      {
        "office_code": "US",
        "pipeline_status": "ok",
        "coverage_through": "2026-09-13T23:59:59.000Z",
        "last_completed_sync_at": "2026-09-14T06:10:00.000Z",
        "last_search_indexed_at": "2026-09-14T06:24:00.000Z",
        "slo_hours": 48,
        "declined_runs_unresolved": 0
      },
      {
        "office_code": "CA",
        "pipeline_status": "lagging",
        "coverage_through": "2026-09-01T23:59:59.000Z",
        "last_completed_sync_at": "2026-09-13T05:40:00.000Z",
        "last_search_indexed_at": "2026-09-13T05:52:00.000Z",
        "slo_hours": 240,
        "declined_runs_unresolved": 1
      }
    ],
    "pipeline": {
      "last_verified_end_to_end_at": "2026-09-14T08:00:00.000Z",
      "last_real_record_alert_at": "2026-09-14T02:14:00.000Z",
      "verification": "canary"
    },
    "request_id": "req_2mR8vNkT"
  }
  ```
</ResponseExample>

## Related Endpoints

* [Watch Attestation](/api-reference/monitoring/watches/attestation) - the monthly, per-watch record, as opposed to this live snapshot
* [Watch Diagnostics](/api-reference/monitoring/watches/diagnostics) - explain a single expected alert
* [List Watches](/api-reference/monitoring/watches/list) - the individual watches behind `watches.by_health`
* [Monitoring status guide](/guides/monitoring/monitoring-status) - health states and the null-honest rule