Skip to Content
Welcome to the Novantra documentation.
DevelopersREST APIGovernance referenceMonitoring

Monitoring

The Monitoring endpoints expose monitor definitions (the rules), monitor runs (each execution), and monitor result items (the per-population outcomes).

This is a read-only surface in v1. Creating, updating, running, pausing, and retiring monitors happens in the Novantra UI (see the Monitoring user guide).

For shared conventions (auth, errors, pagination, ID format), read v1 conventions first.

Scope required

EndpointScope
All read endpoints belowgovernance.monitoring:read

Endpoints

List monitor definitions

GET /api/v1/governance/monitoring/definitions
Authorization: Bearer <access-token>

Query parameters:

ParameterTypeNotes
statusstringOptional. Filter by status: draft, active, paused, retired.

Response:

{
  "monitorDefinitions": [
    {
      "id": "monit_01HXY...",
      "monitorKey": "privileged-access-quarterly-review",
      "title": "Privileged access quarterly review",
      "description": "Every privileged account must have a review record within the last 90 days.",
      "status": "active",
      "subjectModuleKey": "controls",
      "subjectResourceType": "control",
      "subjectResourceId": "ctrl_01HXY...",
      "ownerResponsibilityAssignmentId": "ra_01HXY...",
      "createdAt": "2026-03-01T08:21:43.000Z",
      "updatedAt": "2026-05-25T14:08:33.000Z",
      "lastRunAt": "2026-05-29T03:00:00.000Z"
    }
  ],
  "pagination": {}
}

Get one monitor definition

GET /api/v1/governance/monitoring/definitions/:monitorId
Authorization: Bearer <access-token>

Returns the single-definition shape from the list above.

List monitor runs

GET /api/v1/governance/monitoring/runs
Authorization: Bearer <access-token>

Query parameters:

ParameterTypeNotes
monitorDefinitionIdstringOptional. Filter to runs of one monitor.
resultstringOptional. Filter by aggregate result: pass, fail, warning, unknown.

Response:

{
  "monitorRuns": [
    {
      "id": "monrun_01HXY...",
      "monitorDefinitionId": "monit_01HXY...",
      "triggerKind": "scheduled",
      "aggregateResult": "fail",
      "passCount": 1243,
      "failCount": 4,
      "warningCount": 0,
      "unknownCount": 0,
      "startedAt": "2026-05-29T03:00:00.000Z",
      "completedAt": "2026-05-29T03:00:14.000Z"
    }
  ],
  "pagination": {}
}

Get one monitor run

GET /api/v1/governance/monitoring/runs/:runId
Authorization: Bearer <access-token>

Returns the single-run shape from the list above.

List monitor result items

GET /api/v1/governance/monitoring/result-items
Authorization: Bearer <access-token>

Query parameters:

ParameterTypeNotes
monitorRunIdstringRequired. Filter to items of one run (mandatory because cross-run item walks are expensive).
resultstringOptional. Filter by item result.

Response:

{
  "monitorResultItems": [
    {
      "id": "moritem_01HXY...",
      "monitorRunId": "monrun_01HXY...",
      "itemKey": "user-jane.doe@example.com",
      "result": "fail",
      "itemSnapshot": null,
      "createdAt": "2026-05-29T03:00:11.000Z"
    }
  ],
  "pagination": {}
}

Field notes

subjectModuleKey, subjectResourceType, subjectResourceId

The governed object the monitor applies to. Typically a control, an obligation, or an asset class. See Attaching records to governed subjects.

Result categories

The four result values are:

  • pass — the population item met the rule.
  • fail — it did not meet the rule.
  • warning — it met the rule but with a soft concern (used by some pass policies).
  • unknown — the monitor could not determine the result (data missing, source unavailable). Treat unknown as needing attention; not as a pass.

Aggregate vs item-level

A monitor run carries an aggregate result (pass, fail, etc.) derived from its pass policy. Individual items in the run carry per-item results. A monitor with a threshold-percentage pass policy might have an aggregate pass even with some failing items, because the failing percentage stayed within the threshold.

Population definitions and rule snapshots

In the in-product UI, monitor definitions carry rich snapshots: the population definition (who or what is being checked), the rule definition (the expected condition), the data source posture, pass and failure policies. In v1 these structured snapshots are not exposed in the API surface; reads return the durable identifying fields. Full configuration lives in the in-product UI.

Real-case integration: feeding monitor results into an observability platform

A platform engineering team operates an observability platform (a typical stack with metrics, traces, and alerts). They want monitor failure rates to be a first-class signal alongside CPU usage, error rates, and customer impact metrics, so that a governance failure shows up in the same dashboard as a latency anomaly.

The integration is a small service that polls the Monitoring API:

  1. Calls GET /api/v1/governance/monitoring/runs?result=fail every five minutes to pull recent failed runs.
  2. For each run, calls GET /api/v1/governance/monitoring/definitions/:id to enrich with the monitor’s subject and owner.
  3. Pushes a metric per monitor to the observability platform: governance.monitor.fail_count{monitor=<key>, subject=<control_key>}.
  4. The observability platform’s alerting fires when failure counts exceed configured thresholds.

The service account holds exactly governance.monitoring:read. Five-minute polling is well within rate limits. The integration’s value is making governance posture visible in the platform where engineers already look.

A variation: pull result-items for any newly-failed run, so the observability platform can show the specific failing items inline.

Last updated on
ExceptionsIndicators