Monitor Service

Manage HTTP, TCP, and DNS monitors. The Monitor Service provides 15 RPC methods for creating, updating, listing, triggering, deleting, querying monitor status and metrics, and inspecting HTTP response logs.

All examples assume you have created a client:

import { createOpenStatusClient } from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

HTTP Monitors

Create HTTP Monitor

import {
  createOpenStatusClient,
  HTTPMethod,
  NumberComparator,
  Periodicity,
  Region,
  StringComparator,
} from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
  monitor: {
    name: "My API",
    url: "https://api.example.com/health",
    periodicity: Periodicity.PERIODICITY_1M,
    method: HTTPMethod.HTTP_METHOD_GET,
    regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
    active: true,
    timeout: BigInt(30000),
    retry: BigInt(3),
    followRedirects: true,
    degradedAt: BigInt(5000),
    headers: [
      { key: "Authorization", value: "Bearer my-token" },
    ],
    statusCodeAssertions: [
      { comparator: NumberComparator.EQUAL, target: BigInt(200) },
    ],
    bodyAssertions: [
      { comparator: StringComparator.CONTAINS, target: '"status":"ok"' },
    ],
    headerAssertions: [
      {
        key: "content-type",
        comparator: StringComparator.CONTAINS,
        target: "application/json",
      },
    ],
    description: "Health check for the production API",
    public: false,
    openTelemetry: {
      endpoint: "https://otel.example.com/v1/traces",
      headers: [{ key: "Authorization", value: "Bearer otel-token" }],
    },
  },
});

console.log(`Created monitor: ${monitor?.id}`);

Update HTTP Monitor

Updates are partial — only include the fields you want to change.

const { monitor } = await client.monitor.v1.MonitorService.updateHTTPMonitor({
  id: "123456",
  monitor: {
    name: "Updated API Monitor",
    active: false,
  },
});

HTTP Monitor Options

Option	Type	Required	Description
`name`	string	Yes	Monitor name (max 256 chars)
`url`	string	Yes	URL to monitor (max 2048 chars)
`periodicity`	Periodicity	Yes	Check interval
`method`	HTTPMethod	No	HTTP method (default: GET)
`body`	string	No	Request body
`headers`	Headers[]	No	Custom headers `{ key, value }[]`
`timeout`	bigint	No	Timeout in ms (default: 45000, max: 120000)
`retry`	bigint	No	Retry attempts (default: 3, max: 10)
`followRedirects`	boolean	No	Follow redirects (default: true)
`regions`	Region[]	No	Regions for checks
`active`	boolean	No	Enable monitoring (default: false)
`public`	boolean	No	Public visibility (default: false)
`degradedAt`	bigint	No	Latency threshold (ms) for degraded status
`description`	string	No	Monitor description (max 1024 chars)
`statusCodeAssertions`	StatusCodeAssertion[]	No	Status code assertions
`bodyAssertions`	BodyAssertion[]	No	Body assertions
`headerAssertions`	HeaderAssertion[]	No	Header assertions
`openTelemetry`	OpenTelemetryConfig	No	OpenTelemetry export configuration

TCP Monitors

Create TCP Monitor

import {
  createOpenStatusClient,
  Periodicity,
  Region,
} from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

const { monitor } = await client.monitor.v1.MonitorService.createTCPMonitor({
  monitor: {
    name: "Database",
    uri: "db.example.com:5432",
    periodicity: Periodicity.PERIODICITY_5M,
    regions: [Region.FLY_AMS, Region.FLY_IAD],
    active: true,
  },
});

Update TCP Monitor

const { monitor } = await client.monitor.v1.MonitorService.updateTCPMonitor({
  id: "123456",
  monitor: {
    name: "Updated Database Monitor",
  },
});

TCP Monitor Options

Option	Type	Required	Description
`name`	string	Yes	Monitor name (max 256 chars)
`uri`	string	Yes	`host:port` to monitor (max 2048 chars)
`periodicity`	Periodicity	Yes	Check interval
`timeout`	bigint	No	Timeout in ms (default: 45000, max: 120000)
`retry`	bigint	No	Retry attempts (default: 3, max: 10)
`regions`	Region[]	No	Regions for checks
`active`	boolean	No	Enable monitoring (default: false)
`public`	boolean	No	Public visibility (default: false)
`degradedAt`	bigint	No	Latency threshold (ms) for degraded status
`description`	string	No	Monitor description (max 1024 chars)
`openTelemetry`	OpenTelemetryConfig	No	OpenTelemetry export configuration

DNS Monitors

Create DNS Monitor

import {
  createOpenStatusClient,
  Periodicity,
  RecordComparator,
  Region,
} from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

const { monitor } = await client.monitor.v1.MonitorService.createDNSMonitor({
  monitor: {
    name: "DNS Check",
    uri: "example.com",
    periodicity: Periodicity.PERIODICITY_10M,
    regions: [Region.FLY_AMS],
    active: true,
    recordAssertions: [
      {
        record: "A",
        comparator: RecordComparator.EQUAL,
        target: "93.184.216.34",
      },
      {
        record: "CNAME",
        comparator: RecordComparator.CONTAINS,
        target: "cdn",
      },
    ],
  },
});

Update DNS Monitor

const { monitor } = await client.monitor.v1.MonitorService.updateDNSMonitor({
  id: "123456",
  monitor: {
    name: "Updated DNS Check",
  },
});

DNS Monitor Options

Option	Type	Required	Description
`name`	string	Yes	Monitor name (max 256 chars)
`uri`	string	Yes	Domain to resolve (max 2048 chars)
`periodicity`	Periodicity	Yes	Check interval
`timeout`	bigint	No	Timeout in ms (default: 45000, max: 120000)
`retry`	bigint	No	Retry attempts (default: 3, max: 10)
`regions`	Region[]	No	Regions for checks
`active`	boolean	No	Enable monitoring (default: false)
`public`	boolean	No	Public visibility (default: false)
`degradedAt`	bigint	No	Latency threshold (ms) for degraded status
`description`	string	No	Monitor description (max 1024 chars)
`recordAssertions`	RecordAssertion[]	No	DNS record assertions
`openTelemetry`	OpenTelemetryConfig	No	OpenTelemetry export configuration

List Monitors

List all monitors with offset-based pagination. Returns monitors grouped by type.

const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =
  await client.monitor.v1.MonitorService.listMonitors({
    limit: 10,
    offset: 0,
  });

console.log(`Total: ${totalSize}`);
console.log(`HTTP: ${httpMonitors.length}`);
console.log(`TCP: ${tcpMonitors.length}`);
console.log(`DNS: ${dnsMonitors.length}`);

Pagination parameters:

Parameter	Type	Description
`limit`	number (optional)	Max results to return (1–100, default 50)
`offset`	number (optional)	Number of results to skip (default 0)

Get Monitor

Get a single monitor by ID. The response uses a MonitorConfig oneof type that contains one of HTTP, TCP, or DNS configuration.

const { monitor } = await client.monitor.v1.MonitorService.getMonitor({
  id: "123456",
});

if (monitor?.config.case === "http") {
  console.log(`HTTP Monitor: ${monitor.config.value.name} — ${monitor.config.value.url}`);
} else if (monitor?.config.case === "tcp") {
  console.log(`TCP Monitor: ${monitor.config.value.name} — ${monitor.config.value.uri}`);
} else if (monitor?.config.case === "dns") {
  console.log(`DNS Monitor: ${monitor.config.value.name} — ${monitor.config.value.uri}`);
}

Trigger Monitor

Trigger an immediate check for a monitor.

const { success } = await client.monitor.v1.MonitorService.triggerMonitor({
  id: "123456",
});

console.log(`Trigger successful: ${success}`);

Delete Monitor

const { success } = await client.monitor.v1.MonitorService.deleteMonitor({
  id: "123456",
});

Get Monitor Status

Get the current status of a monitor across all configured regions.

import {
  createOpenStatusClient,
  MonitorStatus,
  Region,
} from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

const { id, regions } = await client.monitor.v1.MonitorService.getMonitorStatus(
  { id: "123456" },
);

for (const { region, status } of regions) {
  console.log(`${Region[region]}: ${MonitorStatus[status]}`);
}

Get Monitor Summary

Get aggregated metrics and latency percentiles for a monitor over a time range.

import { createOpenStatusClient, TimeRange } from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

const summary = await client.monitor.v1.MonitorService.getMonitorSummary({
  id: "123456",
  timeRange: TimeRange.TIME_RANGE_7D,
  regions: [],
});

console.log(`Last ping: ${summary.lastPingAt}`);
console.log(`Successful: ${summary.totalSuccessful}`);
console.log(`Degraded: ${summary.totalDegraded}`);
console.log(`Failed: ${summary.totalFailed}`);
console.log(`P50: ${summary.p50}ms`);
console.log(`P75: ${summary.p75}ms`);
console.log(`P90: ${summary.p90}ms`);
console.log(`P95: ${summary.p95}ms`);
console.log(`P99: ${summary.p99}ms`);

The latency fields (p50, p75, p90, p95, p99) and count fields (totalSuccessful, totalDegraded, totalFailed) are bigint values. The regions parameter is optional — pass an empty array to get metrics across all regions.

getMonitorSummary returns a single aggregate over the window and TimeRange caps at 14 days. For a per-day series to render status bars, use getPageComponentDailySummary on the Status Page Service — it returns per-component daily buckets merged with the incident and maintenance timeline (max 45 days), the single source of truth for the status-bar / status-calendar registry components. The REST endpoint GET /v1/monitor/{id}/summary also exposes a single-monitor daily series ({ ok, count, day }).

List Monitor HTTP Response Logs

List HTTP response logs for a monitor within the 14-day retention window. Supports time-window filtering and offset-based pagination.

Caution

Response logs are a paid feature. On the free plan these methods return permission_denied ("Upgrade for response logs").

import {
  createOpenStatusClient,
  HTTPResponseLogRequestStatus,
  HTTPResponseLogTrigger,
  Region,
} from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

const { logs, pagination } = await client.monitor.v1.MonitorService
  .listMonitorHTTPResponseLogs({
    id: "123456",
    fromTimestamp: BigInt(Date.now() - 24 * 60 * 60 * 1000),
    toTimestamp: BigInt(Date.now()),
    limit: 25,
    offset: 0,
  });

for (const log of logs) {
  console.log(
    `[${Region[log.region]}] ${log.timestamp}: ` +
      `${log.statusCode ?? "n/a"} (${log.latency}ms) ` +
      `status=${HTTPResponseLogRequestStatus[log.requestStatus]} ` +
      `trigger=${HTTPResponseLogTrigger[log.trigger]}`,
  );
}

if (pagination?.hasMore) {
  console.log(`Next offset: ${pagination.nextOffset}`);
}

Request parameters:

Parameter	Type	Description
`id`	string	Monitor ID (required)
`fromTimestamp`	bigint (optional)	Window start, Unix milliseconds (14d retention)
`toTimestamp`	bigint (optional)	Window end, Unix milliseconds
`limit`	number (optional)	Max results to return (1–100, default 25)
`offset`	number (optional)	Number of results to skip (default 0)

Each HTTPResponseLogListItem includes id, latency, statusCode, monitorId, requestStatus, region, cronTimestamp, trigger, timestamp, and an optional timing breakdown (dns, connect, tls, ttfb, transfer).

Get Monitor HTTP Response Log

Get full debugging details for a single response log: the requested URL, redacted response headers, error message, and serialized assertions. Same plan gating as above.

const { log } = await client.monitor.v1.MonitorService
  .getMonitorHTTPResponseLog({
    id: "123456",
    logId: "log_456",
  });

console.log(`URL: ${log?.url}`);
console.log(`Errored: ${log?.error}`);
console.log(`Status code: ${log?.log?.statusCode}`);
console.log(`Assertions: ${log?.assertions ?? "n/a"}`);

The log.log field embeds the same HTTPResponseLogListItem returned by listMonitorHTTPResponseLogs, so timing and classification fields are available alongside the detail fields.