Api Monitoring

API Monitoring

Overview

A Monitor is a recurring, scheduled check against a live API. The CLI now owns its full lifecycle: monitor create/update/delete/pause/resume manage the schedule and configuration, monitor list/get discover and inspect existing ones, monitor run triggers an ad hoc run, and monitor jobs/monitor runs inspect what actually happened during a run. There is no remaining task here that has to go through the Postman app.

postman runner is a separate, infrastructure-level concern: it starts a self-hosted execution agent so Monitor runs can reach APIs that live behind a private network Postman's cloud can't reach directly, and it lists the values (Postman regions or self-hosted runner ids) that monitor create/update --runner accepts.

Creating and scheduling a monitor

monitor create -c <collectionId> is the minimum — name defaults to the linked collection's own name. Workspace comes from -w, or falls back to the workspace named in the local .postman/resources.yaml manifest; without either, creation fails. --schedule <cron> plus --timezone (defaults to the host machine's zone) set when it fires; --runner (repeatable) says where from — a Postman region name (postman runner regions) or a self-hosted runner's id (postman runner list), and both can be mixed in the same monitor. --notify-email (repeatable) and --notification-limit control failure alerts. The run itself is shaped by the same options as a collection run — --retry (service caps at 2), --timeout, --delay, --strict-ssl/--insecure, --follow-redirects/--block-redirects, and dataset iteration via --dataset-id/--dataset-view-id/--iteration-count/ --iteration-strategy. Creation triggers an immediate run by default; pass --no-run-now to skip that.

Updating, pausing, and deleting

monitor update <monitorId> takes the same schedule/runner/notification/ run-option flags as create, plus --clear-notifications to wipe every recipient. It cannot change the linked collection or environment — delete and recreate the monitor instead — and it does not pause or resume; use monitor pause/monitor resume for that. monitor delete <monitorId> prompts for confirmation unless -y/--yes is passed, and is permanent.

Discovering and inspecting monitors

monitor list filters by -w/-c/--environment/--owner/--team/ --active. --runner <id> filters to a self-hosted runner id (not a Postman region) and can't be combined with the other filters. Page with --limit/--cursor; --offset is accepted by the service but silently ignored, so the CLI rejects it locally rather than returning a page that looks right but isn't — use --cursor from the previous page's response. --columns picks which fields show, -f/--filter matches on name within the page already returned (not a server-side search), and --sort name|active orders it. monitor get <monitorId> shows one monitor's full configuration.

Triggering a run

monitor run <monitorId> runs an existing Monitor synchronously and prints the result — useful in CI to get a pass/fail right after a deploy rather than waiting for the next scheduled tick. -t/--timeout (default 15 minutes) caps how long the CLI waits for completion; a timeout hit here is the CLI giving up on waiting, not the Monitor itself failing. --async submits the run and returns immediately with its job id and Postman URL instead of waiting at all — reach for this over a long -t when the caller doesn't need the verdict inline. --json prints only the verdict as JSON, for scripting. -x/--suppress-exit-code overrides the default fail-on-failed-run exit code, for a caller that wants to see failures without breaking a pipeline step.

Diagnosing a run

monitor jobs list <monitorId> lists a monitor's recent jobs; monitor jobs get <jobId> reports one job's terminal state and its per-region run outcomes — a monitor with runners in multiple regions runs once per region per job. monitor runs get <runId> goes one level deeper: which test assertions ran during one attempt, which failed, and why. Reach for these instead of re-running blind after a -t timeout, or whenever the task is explaining why a monitor failed rather than just that it did.

Self-hosted runners

runner start --id <id> --key <key> (from the Postman app) registers a runner that executes monitor runs from your own infrastructure instead of Postman's cloud. This matters only when the monitored API isn't reachable from the public internet — a public API needs no self-hosted runner. Extra flags cover the runner's own networking: --region eu for EU residency, --proxy/--egress-proxy/--egress-proxy-authz-url for outbound routing, --ssl-extra-ca-certs for a private CA, and --metrics/--metrics-port for a health-check endpoint. Analytics are sent by default; --no-report-events opts out. runner list shows the team's registered self-hosted runners — feed an id from here into monitor create/update --runner or monitor list --runner. runner regions lists the Postman-region and private-runner values valid for --runner on monitor create/update, including a static IP where one is configured — check here before guessing a region string.

Critical Rules

1. Monitor creation and scheduling are real CLI tasks now. Don't send the user to the Postman app for this — monitor create with -c and --schedule does it. Notifications here are email only (--notify-email); a request for a different alert channel (Slack, a webhook) is the one piece still worth checking against the app rather than assuming a flag exists.
2. update can't move a monitor to a different collection or environment, and doesn't pause/resume it. Delete and recreate for the former; use pause/resume for the latter.
3. A monitor run -t timeout is a wait cap, not a monitor failure. Don't report "the monitor failed" from a timeout without checking monitor jobs get/monitor runs get (or the Postman app) for what the run actually did after the CLI gave up waiting — or avoid the wait entirely with --async.
4. --runner on monitor create/update takes a region name or a self-hosted runner id — check runner regions/runner list before guessing a string, and don't suggest runner start unless the target API genuinely isn't reachable from Postman's cloud.
5. monitor list --offset doesn't work — use --cursor, and --runner there can't be combined with the other filters.
6. monitor delete is permanent. Confirm intent before passing -y to skip its prompt.

Verification

State the monitor/job/run id and the actual pass/fail result or configuration change, not just that the command exited. For run, state whether it completed synchronously or was submitted --async (a job id is not yet a verdict — resolve it with monitor jobs get before reporting a result). If a self-hosted runner was started, confirm it registered (the Postman app, or runner list, shows it as connected) before assuming monitor runs will route through it.