Postman CLI monitoring and performance commands

The collection to monitor. Accepts the collection ID in the prefixed or bare form shown in the Postman app.

Runs only the requests or folders you select, in the order you set. Accepts a request or folder ID. Repeat the option to include more. By default, the monitor runs every request in the collection.

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.

The ID of the monitor to update.

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.

Runs only the requests or folders you select, in the order you set. This replaces the monitor’s current selection. Accepts a request or folder ID. Repeat the option to include more. Can’t be combined with --clear-items.

Clears the monitor’s request selection so it runs every request in its collection again. Can’t be combined with -i, --item.

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.

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.

The ID of the monitor to show.

Prints the monitor’s configuration as JSON instead of a table.

The ID of the monitor to pause.

Prints the result as JSON instead of a table.

The ID of the monitor to resume.

Prints the result as JSON instead of a table.

The ID of the monitor to delete.

Skips the confirmation prompt.

Prints the outcome, including any failure, as JSON instead of a plain message.

The unique identifier of the monitor to run.

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.

The ID of the monitor whose jobs to list.

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.

The ID of the job to report on.

Prints the result as JSON instead of a table.

The ID of the run to report on.

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.

The ID of the monitor to show metrics for.

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.

Specifies the runner ID.

Specifies the runner key that authenticates your runner with the Postman Cloud.

Specifies a folder on the runner’s computer that holds the JDBC driver JAR files. Required to run a monitor that uses a dataset with a custom JDBC data source. The runner loads drivers only from this folder and matches them by file name, so the driver paths saved in the dataset are ignored.

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 you pass --report-events. To turn reporting off, pass --report-events=false. You can also use --no-report-events.

Filters the results to the runners in a specific workspace.

Prints the runner list as JSON instead of a table.

Prints the region list as JSON instead of a table.

The unique identifier of the collection to run performance tests against, or the path to a local collection.

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.

Replaces all symbols in the output with their plain text equivalents.

The duration of the performance test, as a whole number of minutes. A value with a unit, such as 30s or 1h, returns an error, so convert it to minutes first.

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.

Turns off SSL certificate verification for the target. Supported only with --runner local, the default.

The load profile type to use for the performance test. Accepts fixed, ramp-up, spike, or peak. Each profile breaks the test duration into phases. Use --load-segments to set how long each phase lasts, or --base-vu to set the floor virtual user count. With --base-vu, omitted phases and the floor fall back to the following defaults:

• With fixed, virtual users hold at --peak-vu for the whole duration. --base-vu and --load-segments don’t apply.
• With ramp-up, virtual users hold at the floor (25% of peak by default) for the first 25% of the duration, ramp up to peak over the next 25%, then hold at peak for the rest.
• With spike, virtual users hold at the floor (10% of peak by default) for the first 40% of the duration, ramp up to peak over the next 10%, ramp back down to the floor over the following 10%, then hold at the floor for the rest. This profile doesn’t hold at the peak itself, so use peak to hold there.
• With peak, virtual users hold at the floor (20% of peak by default) for the first 20% of the duration, ramp up to peak over the next 20%, hold at peak for the following 20%, ramp back down to the floor over the next 20%, then hold at the floor for the rest.

The peak (maximum) virtual users that simulate traffic to your API. Must be a whole number. Same option as --vu-count. Use one or the other, but not both. Cloud runs require a minimum of 10 virtual users.

The base (floor) virtual users the run starts from. Not supported with --load-profile fixed, which runs flat at --peak-vu. Must be at least 1 and a whole number less than --peak-vu. Defaults to a percentage of --peak-vu that depends on --load-profile.

The duration of each phase of the load profile, as a comma-separated list in the order the phases run. Leave a position empty to keep its default, so you can set only the phases you care about. Each duration is a whole number of minutes, or a number with a unit, such as 30s, 1m30s, or 10m.

• ramp-up takes 2 segments: warm-up, ramp-up.
• spike takes 3 segments: warm-up, ramp-up, ramp-down.
• peak takes 4 segments: warm-up, ramp-up, hold, ramp-down.
• fixed takes no segments.

The segments you set must fit inside --duration, or the run is refused before it starts. Only a segment left at its default is ever shrunk to make room. A segment you gave an explicit duration to never shrinks, so it has to fit inside --duration on its own.

For example, on peak, --load-segments ,,5m, sets only the hold phase to 5 minutes and leaves the rest at their defaults. On spike, --load-segments ,20s,10s sets the ramp-up and ramp-down phases, leaving warm-up at its default.

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. The final summary event includes a recorded field. For a local run that isn’t recorded, recorded is false and runNumber is null.

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 job that started the run. This applies to both local and cloud runs.

Repeatable. Pass --pass-if more than once to require every condition to pass. The test fails if any one condition doesn’t pass.

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%.
• --pass-if "less_than(p95, 500)" --pass-if "less_than(error_rate, 5)" — The test passes only if both conditions hold.

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.

The two cloud runners accept a collection ID, or the path to a local collection that’s linked to a cloud collection in .postman/resources.yaml. Any other local path returns an error. To run another local collection, use --runner local.

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. Works with every runner, including the default --runner local. Learn more about running a performance test with setup and teardown collections.

Specifies the path to a client certificate (PEM) to present to mutual TLS (mTLS) targets. Supported only with --runner local, the default.

Specifies the path to a client certificates configuration file (JSON) that maps certificates to hosts, for per-URL client certificates. Supported only with --runner local, the default.

Specifies the path to the client certificate’s private key. Supported only with --runner local, the default.

Specifies the passphrase for a protected client certificate key. Supported only with --runner local, the default.

Specifies the path to additional trusted CA certificates (PEM) for the target, such as an internal certificate authority. Supported only with --runner local, the default.

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. Works with every runner, including the default --runner local.

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.

Previous name for --peak-vu. Use one or the other, but not both. Cloud runs require a minimum of 10 virtual users.

The ID of the performance run to get.

The output format for the results.

Prints the result as JSON for machine-readable output. An alias for --output json.

The time to wait for the service before failing, in milliseconds.

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.

The output format for the results.

Prints the results as JSON for machine-readable output. An alias for --output json.

The time to wait for the service before failing, in milliseconds.