Monitoring and performance commands
This topic covers monitoring and performance testing commands for the Postman CLI.
Use the postman monitor commands to create, configure, run, and manage monitors, and to inspect their run history, all from the command line. Use the postman runner commands to run your organization’s APIs from your internal network with Private API Monitoring, and to list the runners and regions a monitor can run from. The postman performance run command runs performance tests for your collections from your CI/CD pipeline.
All monitor and runner commands accept --api-key <key> to authenticate with a Postman API key instead of your postman login session, falling back to the POSTMAN_API_KEY environment variable, so the reference below omits it. Where a command can print machine-readable output, its options include --json.
The postman monitor commands also accept the guest session that postman init creates, so you can run them without signing in first. To learn more, see postman signup.
postman monitor create
Creates a collection-based monitor. Specify the collection to monitor, then optionally set a schedule, choose where the monitor runs, and configure notifications and run options. By default, the monitor runs once after you create it. Pass --no-run-now to skip that first run.
Usage
Options
The collection to monitor. Accepts the collection ID in the prefixed or bare form shown in the Postman app.
A name for the monitor. Defaults to the monitored collection’s name.
An environment to run the monitored collection with.
The workspace to create the monitor in. Defaults to the workspace named in your .postman/resources.yaml file, and is required if that file doesn’t name one.
A cron expression that sets how often the monitor runs, for example 0 9 * * MON.
The time zone for --schedule, for example America/New_York. Defaults to the host machine’s time zone. Requires --schedule.
Where the monitor runs. Accepts a Postman region name (list them with postman runner regions) or the ID of a self-hosted runner (list them with postman runner list). Repeat the flag to run from more than one location.
An email address to notify when a run fails or errors. Repeat the flag to notify more than one address, up to five.
The number of consecutive failure notifications to send before muting them. The service accepts a value from 1 to 99.
The number of times to retry a failed run. The service caps this at 2.
The request timeout in milliseconds.
The delay between requests in milliseconds.
Fails the run when the target’s TLS certificate can’t be verified. Can’t be used with --insecure.
Skips TLS certificate verification for the monitored target. Can’t be used with --strict-ssl.
Follows HTTP redirects during the run. Can’t be used with --block-redirects.
Doesn’t follow HTTP redirects during the run. Can’t be used with --follow-redirects.
A dataset to use as iteration data. Used together with --dataset-view-id.
The dataset view to iterate. Used together with --dataset-id.
The number of iterations to run.
How iteration data is consumed. Accepts round_robin, repeat_last, or stop_at_end. Requires --iteration-count, --dataset-id, and --dataset-view-id.
Skips the immediate run that otherwise happens after you create the monitor.
Prints the result as JSON instead of a table.
Examples
postman monitor update
Updates a monitor’s schedule, runner, notifications, environment, or run options. Specify the monitor by its ID. This command can’t change a monitor’s linked collection. A monitor’s collection is fixed once it’s created, so to run a different collection, create a new monitor. It also doesn’t pause or resume a monitor. Use postman monitor pause and postman monitor resume for that.
Usage
The ID of the monitor to update.
Options
A new name for the monitor.
An environment to run the monitored collection with. This replaces the monitor’s current environment.
Runs the monitored collection with no environment. Can’t be combined with -e, --environment.
A new cron expression for the monitor’s schedule.
The time zone for --schedule, for example America/New_York. Defaults to the host machine’s time zone.
Where the monitor runs. Accepts a Postman region name (see postman runner regions) or a self-hosted runner ID (see postman runner list). Repeat the flag to set more than one. This replaces the monitor’s current set of runners.
An email address to notify when a run fails or errors. Repeat the flag to notify more than one address, up to five. This replaces the monitor’s current list of recipients.
Removes every notification recipient from the monitor.
The number of consecutive failure notifications to send before muting them. The service accepts a value from 1 to 99.
The number of times to retry a failed run. The service caps this at 2.
The request timeout in milliseconds.
The delay between requests in milliseconds.
Fails the run when the target’s TLS certificate can’t be verified. Can’t be used with --insecure.
Skips TLS certificate verification for the monitored target. Can’t be used with --strict-ssl.
Follows HTTP redirects during the run. Can’t be used with --block-redirects.
Doesn’t follow HTTP redirects during the run. Can’t be used with --follow-redirects.
A dataset to use as iteration data. Used together with --dataset-view-id.
The dataset view to iterate. Used together with --dataset-id.
The number of iterations to run.
How iteration data is consumed. Accepts round_robin, repeat_last, or stop_at_end. Requires --iteration-count, --dataset-id, and --dataset-view-id.
Prints the result as JSON instead of a table.
Examples
postman monitor list
Lists the monitors visible to you. Use the filter options to narrow the results, and the column and sort options to control the output. In the results, a monitor’s Status is Paused when it’s paused. Otherwise, it’s the last run’s health: Healthy, Unhealthy, or Unknown if it hasn’t run yet.
Usage
Options
Filters to monitors in this workspace.
Filters to monitors on this collection.
Filters to monitors on this environment.
Filters to a self-hosted runner ID, not a Postman region. Can’t be combined with --workspace, --collection, --environment, --owner, --team, or --active.
Filters to monitors created by this user ID, shown in the Owner column.
Filters to monitors owned by your team.
Filters by active state.
The maximum number of monitors to return. The service caps the page size and rejects a larger value.
A pagination cursor from a previous page’s response.
A comma-separated list of columns to show. Defaults to Name, Status, ID, Schedule, Owner, and Collection. Also available: State, Notifications, Environment, and Runners.
Omits the header row.
Shows only monitors whose name contains this text. Applies to the returned page and is case-insensitive.
Sorts the returned page by name or active.
Prints the results as JSON instead of a table.
Examples
postman monitor get
Shows a monitor’s configuration. Specify the monitor by its ID.
Usage
The ID of the monitor to show.
Options
Prints the monitor’s configuration as JSON instead of a table.
Example
postman monitor pause
Pauses a monitor so it stops running on its schedule. Specify the monitor by its ID. Resume it later with postman monitor resume.
Usage
The ID of the monitor to pause.
Options
Prints the result as JSON instead of a table.
Example
postman monitor resume
Resumes a paused monitor so it runs on its schedule again. Specify the monitor by its ID.
Usage
The ID of the monitor to resume.
Options
Prints the result as JSON instead of a table.
Example
postman monitor delete
Permanently deletes a monitor. Specify the monitor by its ID. The command prompts for confirmation unless you pass --yes.
Usage
The ID of the monitor to delete.
Options
Skips the confirmation prompt.
Prints the outcome, including any failure, as JSON instead of a plain message.
Examples
postman monitor run
This command runs a monitor in the Postman cloud. Add the command into your CI/CD script to trigger a monitor run during your deployment process. Then your team can use your Postman tests to catch regressions and configuration issues. Learn more at Run a monitor using the Postman CLI.
By default, the command invokes the monitor and polls Postman for the run’s completion, returning the monitor results. Specify the monitor with its monitor ID. Pass --async to submit the run and return without waiting for it to finish.
You can find the monitor ID in Postman. Click the 
Services tab, click Monitors in the sidebar, and select a monitor. Then click the 
Monitor details tab in the right sidebar to view or copy the monitor ID.
Usage
The unique identifier of the monitor to run.
Options
Submits the run and returns its job ID and Postman URL without waiting for the run to finish. Check on it later with postman monitor jobs get.
The maximum time to wait for the run to complete, in milliseconds. Defaults to 900000 (15 minutes).
Specifies whether to override the default exit code for the current run.
Prints the run’s verdict as JSON instead of a table.
Example
Learn more at Run a monitor using the Postman CLI.
postman monitor jobs list
Lists a monitor’s recent jobs. A job is one triggered run of the monitor. Specify the monitor by its ID.
Usage
The ID of the monitor whose jobs to list.
Options
Filters by outcome, for example success, failure, error, or abort. The service validates the value.
Filters by trigger, for example api, schedule, webhook, or postman-cli. The service validates the value.
Shows only jobs that finished at or after this ISO 8601 date-time.
The maximum number of jobs to return.
An opaque pagination cursor.
Prints the results as JSON instead of a table.
Example
postman monitor jobs get
Reports one job’s terminal state and its per-region run outcomes. Specify the job by its ID, which you can get from postman monitor jobs list.
Usage
The ID of the job to report on.
Options
Prints the result as JSON instead of a table.
Example
postman monitor runs get
Reports which test assertions ran during one attempt of a monitor run, which failed, and why. Specify the run by its ID, which you can get from postman monitor jobs get.
Usage
The ID of the run to report on.
Options
Which attempt of the run to show, counting from 0. Defaults to the latest attempt.
Shows only failed assertions.
Prints the results as JSON instead of a table.
Example
postman monitor metrics
Shows a monitor’s per-request latency and outcome history. The command groups each request’s runs by region over a time window and lists the slowest or most error-prone requests first. You can then see which request is slow or failing and how its behavior has trended over time. By default, it covers the last 7 days.
Usage
The ID of the monitor to show metrics for.
Options
Includes only request runs at or after this ISO 8601 date-time. Defaults to the last 7 days.
Includes only request runs at or before this ISO 8601 date-time. Defaults to the current time.
Shows only requests whose name contains this text. The match is case-insensitive.
Limits the number of rows shown. The CLI applies this to the returned results, since the service doesn’t paginate this data.
Prints the results as JSON for machine-readable output, with one row per request run.
Example
postman runner start
Private API Monitoring is available on Postman Enterprise plans.
With Private API Monitoring, you can use runners to monitor and test your organization’s APIs from your internal network, without publicly exposing your endpoints.
Run this command to start a runner from your internal network that regularly polls Postman for upcoming monitor runs. The collection’s tests run in your internal network. Then the test results are sent back to the Postman cloud, making them available in the monitor results. Provide the runner ID and key from the command you copied when you created the runner. Learn more about setting up a runner in your internal network.
Optionally, you can configure the runner to route HTTP and HTTPS traffic through a proxy server that enforces outbound request policies. You can use the --proxy option to provide the URL for the proxy server used by your organization. Or you can use the --egress-proxy option to enable the built-in proxy and use the --egress-proxy-authz-url option to provide the URL for the runner authorization service that evaluates outbound request policies. Learn more about configuring a runner to use a proxy server.
You can’t use the --proxy and --egress-proxy options together.
If the runner is running in the background, stop the runner using your system’s process control. You can also press Control+C or Ctrl+C to stop the runner.
Run events, including monitor runs and average response time, are reported to Postman by default, where they appear in the Monitors section of the API Catalog. To opt out, pass --report-events=false.
To use this command, sign in to Postman with the postman login command.
Usage
Specifies the runner ID.
Specifies the runner key that authenticates your runner with the Postman cloud.
Options
Runs the runner with the built-in proxy enabled. This option requires --egress-proxy-authz-url.
Specifies a custom runner authorization service URL. Instead of specifying this option, you can define the URL using the POSTMAN_RUNNER_AUTHZ_URL environment variable. This is required with --egress-proxy.
Runs a metrics server available at the /health/live endpoint. Useful for health checks in orchestration environments, like Kubernetes.
Specifies a port number where the metrics server can expose health checks and metrics.
Specifies your organization’s proxy URL. Instead of specifying this option, you can define the URL using the HTTP_PROXY and HTTPS_PROXY environment variables.
Specifies the region for the runner. Use eu for the EU region.
Specifies the path to the file with one or more trusted CA certificates in PEM format. Used for custom SSL certificate validation.
Run events are reported to Postman by default, whether or not you pass --report-events. To turn reporting off, pass --report-events=false. You can also use --no-report-events.
Examples
postman runner list
Lists your team’s registered self-hosted runners. Use the runner IDs it returns with the --runner option on postman monitor create or postman monitor update to run a monitor from a self-hosted runner.
Usage
Options
Filters the results to the runners in a specific workspace.
Prints the runner list as JSON instead of a table.
Examples
postman runner regions
Lists the region and private-runner values that are valid for the --runner option on postman monitor create and postman monitor update, including a static IP where one is configured.
Usage
Options
Prints the region list as JSON instead of a table.
Example
postman performance run
The postman performance run command runs a performance test for a specified collection and makes the results available in Postman. By default, the test’s load originates from the machine that invokes the command, such as your local machine or CI/CD environment. Use the --runner option to originate load from Postman’s managed cloud infrastructure instead. Learn more at Configure and validate performance tests using the Postman CLI.
The command runs the performance test against the specified collection, returning the performance test results in Postman. Specify the collection with its ID.
To use this command, sign in to Postman with the postman login command.
Usage
The unique identifier of the collection to run performance tests against.
Options
Specifies the path to a data file with custom values to use for each virtual user. The file must be in CSV or JSON format. Each virtual user uses a random row each time it runs the requests. Can’t be used with --dataset-id or with --runner postman-cloud. To provide data for a cloud run, or to control how rows map to virtual users, use a dataset instead. Learn more about using a data file to simulate virtual users.
Specifies the ID of a dataset to use as iteration data for each virtual user. Must be used with --dataset-view-id. Can’t be used with --data-file. Learn more about using a dataset to simulate virtual users.
Specifies the ID of the dataset view to use. The view controls which rows are available to virtual users during the test. Must be used with --dataset-id.
Controls how rows are assigned to virtual users. Accepts round-robin, fixed, or random. Learn more about strategies.
The duration of the performance test in minutes.
Specifies an environment by its ID. Variables in the collection are resolved from the environment.
Specifies globals by its ID. Variables in the collection are resolved from globals.
The load profile type to use for the performance test. Accepts fixed, ramp-up, spike, or peak.
- With
fixed, the number of virtual users is constant during the performance test. - With
ramp-up, the number of virtual users gradually increases from 25% to 100%, and then maintains at 100%. - With
spike, the number of virtual users starts at 10%, spikes to 100%, then drops back down to 10%. - With
peak, the number of virtual users gradually increases from 20% to 100%, maintains at 100%, then gradually decreases back down to 20%.
The format for the live results the command streams as the test runs. With auto, the default, the command shows an interactive dashboard on a terminal. With ndjson, it streams the results as newline-delimited JSON. This is useful when you pipe or redirect the output, or run the command from an agent or CI, where the dashboard can’t render.
Specifies a condition that determines whether the performance test passes or fails. The condition must be in the function(metric, value) format. When the condition is met, the command exits with code 0. When it isn’t met, the command exits with code 1, which fails the CI/CD job that started the run. This applies to both local and cloud runs.
Functions:
less_than(metric, value)— The test passes if the metric is less than the value.less_than_eq(metric, value)— The test passes if the metric is less than or equal to the value.greater_than(metric, value)— The test passes if the metric is greater than the value.greater_than_eq(metric, value)— The test passes if the metric is greater than or equal to the value.
Metrics:
avg— The response time of all requests averaged together, in milliseconds.p90— The 90th percentile of response times, in milliseconds.p95— The 95th percentile of response times, in milliseconds.p99— The 99th percentile of response times, in milliseconds.error_rate— The percentage of requests with an error. Errors indicate runtime issues such as timeouts, connection or TLS failures, or uncaught exceptions in user scripts.rps— The number of requests sent per second.
Examples:
--pass-if "less_than(p95, 500)"— The test passes if the 95th percentile of response times is less than 500 milliseconds.--pass-if "less_than_eq(error_rate, 5)"— The test passes if the percentage of requests with an error is less than or equal to 5%.
Specifies the API key used to load resources from the Postman API. Only supported in the US region. To authenticate in the EU region, use postman login --region.
Specifies where the performance test’s load originates. Specify one runner for each run. Repeating the option returns an error.
local— Runs on the machine that invokes the command.postman-cloud— Runs on Postman’s managed cloud infrastructure. Requires cloud performance tests to be available on your plan.postman-cloud-static-ip— Runs on a static-IP cluster in the region of your logged-in account (US by default, or EU for EU Data Residency plans), so you can allowlist the load’s source IPs in your firewall. Requires static IPs to be available on your plan.
Specifies the ID of a collection to run once before the performance test starts. Use a setup collection to prepare something the test needs, such as creating an account or requesting an access token. Only a collection ID is supported. Requires the --runner postman-cloud option. Learn more about running a performance test with setup and teardown collections.
Specifies the ID of a collection to run once after the performance test ends, on every outcome, including when the run completes, is canceled, fails, or times out. Use a teardown collection to clean up afterward, such as deleting data the test created. Requires the --runner postman-cloud option.
Redirects requests to a mock while the performance test runs, using the same mapping format as postman collection run --use-mock. Pass --use-mock more than once to redirect multiple mappings. This option applies only to local runs. With --runner postman-cloud, the Postman CLI ignores it and prints a warning.
The number of peak virtual users that simulate traffic to your API. Cloud runs require at least 10 virtual users.
Examples
postman performance list
Lists a collection’s past performance test runs, newest first, so you can review historical results and track trends. Specify the collection with its ID.
Usage
Options
The ID of the collection whose performance runs to list.
A pagination cursor from a previous page’s response. The command returns the newest 25 runs per page. When more are available, it prints a cursor to pass here for the next page.
Prints the results as JSON for machine-readable output.
The time to wait for the service before failing, in milliseconds.