> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. For full content including API reference and SDK examples, see https://learning.postman.com/llms-full.txt.
# Configure and validate performance tests using the Postman CLI
With performance tests, you can simulate user traffic and observe how your API behaves under load. Using the [Postman CLI](/docs/postman-cli/postman-cli-overview/), you can run [performance tests](/docs/tests-and-scripts/performance-testing/testing-api-performance/) for Postman Collections locally or as part of your CI/CD pipeline. This enables your team to automatically detect performance regressions during development and deployment workflows.
The [`postman performance run` command](/docs/postman-cli/postman-cli-monitoring/#postman-performance-run) runs a configured performance test for a collection and makes the results available in Postman. You can use the command to validate performance tests locally, automate them in your CI/CD pipeline, and compare test results across runs to identify performance regressions.
To use the `postman performance run` command, sign in to Postman with [the `postman login` command](/docs/postman-cli/postman-cli-auth#postman-login).
Performance tests aren't supported with the [Postman web app](/docs/getting-started/installation/install-app/#use-the-postman-web-app).
## Prepare a collection for performance testing
Before running a performance test with the Postman CLI, prepare a collection that represents the API traffic you'd like to test. You can [create a new collection](/docs/use/use-collections/create-collections) for performance testing, or reuse an existing collection and modify it for load testing scenarios.
When preparing your collection, choose [requests](/docs/use/send-requests/create-requests/request-basics) that reflect real API usage patterns and critical workflows. For example, you may want to include commonly used endpoints, authentication flows, or requests that are sensitive to latency and throughput. You can also [add `pm.test()` assertions](/docs/tests-and-scripts/write-scripts/test-scripts) to validate response status codes, response times, and other performance-related behaviors during load testing.
You can also use [Agent Mode](/docs/use/agent-mode/overview) to generate a collection for performance testing. For best results, describe the API workflows, endpoints, variables, and assertions you'd like to include in the collection.
For example, you can ask Agent Mode the following:
```text wordWrap
Create a Postman Collection for performance testing an e-commerce API. Include realistic user workflows for product search, product details, user authentication, cart operations, and checkout. Use collection variables for the base URL and authentication token, avoid destructive requests, and add pm.test() assertions for response status codes and response times.
```
## Generate the CLI command and run tests locally
After preparing your collection, configure the performance test in Postman and generate the Postman CLI command. You can run the command locally first to make sure the performance test works as expected before adding it to your CI/CD pipeline.
1. Click the 
**Items** tab in the sidebar.
2. Click **Collections**, then select the collection you'd like to run a performance test for.
3. Click 
**Run**.
4. Click the **Performance** tab.
5. Under **Run**, select **Via the CLI**.
6. Configure the load profile, virtual user count, and test duration.
7. Configure a pass/fail condition for the performance test. This determines whether the performance test passes or fails based on metrics such as percentile response times. You can use this condition in your CI/CD pipeline to prevent deployments that don't meet your performance requirements.
8. Under **Install Postman CLI**, click 
**Copy to clipboard** to copy the Postman CLI installation command.
9. Install the Postman CLI on your local machine.
10. Under **Run the performance test**, click **Add API key**. Do one of the following:
* Click **Generate Key** to create a new API key. Enter a name for the API key and click **Generate**. Click **Copy** to copy the key and save it somewhere safe.
* Click **Use Existing Key** and enter a valid API key.
11. Click **Insert Key**.
12. Click 
**Copy to clipboard** to copy the `login` and `performance` commands.
13. Enter the commands into your terminal and run them locally.
The generated commands include the `postman login` command and the `postman performance run` command. For example:
```bash wordWrap
postman login --with-api-key
postman performance run --vu-count 20 --duration 3 --load-profile spike --pass-if "less_than(p90, 500)"
```
While the test is running, you can view performance metrics in real time from the terminal. To learn how to view performance test results in the Postman app during and after the test run, see [View results in Postman](#view-results-in-postman).
## Run performance tests in your CI/CD pipeline
After you verify that the performance test runs locally, add the `postman performance run` command to your CI/CD pipeline. This enables your team to run performance tests automatically when changes are pushed to your repository.
The following example uses GitHub Actions to install the Postman CLI, authenticate with Postman, and run a performance test when changes are pushed to a GitHub repository. The collection ID is stored as a GitHub Actions variable, and the Postman API key is stored as a GitHub Actions secret.
```yaml
name: Performance Tests
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
performance:
name: Run Performance Test
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Postman CLI
run: |
curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
- name: Login to Postman CLI
run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
- name: Run Postman performance test
run: |
postman performance run "${{ vars.COLLECTION_ID }}" \
--vu-count 20 \
--duration 10 \
--load-profile spike \
--pass-if "less_than(p90, 500)"
```
After adding the workflow file to your repository, commit and push your changes. GitHub Actions starts the workflow and runs the performance test with the Postman CLI. You can use performance tests to prevent deployments that don't meet your performance requirements. In this example, if the performance test exceeds the configured `--pass-if` threshold, the CI/CD workflow fails. You can use the failed run to investigate performance regressions before merging or deploying your changes.
To learn how to view performance test results in the Postman app during and after the test run, see [View results in Postman](#view-results-in-postman).
## View results in Postman
You can review performance test results in Postman to analyze metrics such as response times, requests processed over time, error rates, and percentile-based performance measurements.
If you're on a Postman paid plan, you can view live performance metrics in the Postman app while the Postman CLI test is running. Real-time visibility helps you monitor slow response times, failed assertions, and request errors as they occur during local or CI/CD test runs. If the API becomes unstable under load, you can stop the test, adjust your configuration or API, and rerun the test without waiting for the full run to complete.
After the test completes, all Postman plans can view detailed performance test results in the Postman app. Comparing results across runs can help you identify regressions and validate performance improvements.
To view performance test results, do the following:
1. Click the **Items** tab in the sidebar.
2. Click **Collections**, then select the collection you'd like to view performance test results for.
3. Click the **Runs** tab, then click the **Performance** tab.
4. Select a performance test run to view detailed metrics.
To learn more, see [View metrics for performance tests](/docs/tests-and-scripts/performance-testing/performance-test-metrics).
### Example of a successful run
As an example, a performance test passes when the API remains within the configured `--pass-if` threshold. For example, a workflow using `--pass-if "less_than(p90, 500)"` passes if 90% of requests complete in less than 500 ms. Successful runs can help confirm that recent changes didn't negatively affect API performance.
### Example of a failed run
As an example, a performance test fails when the API exceeds the configured `--pass-if` threshold. For example, changing the threshold to `--pass-if "less_than(p90, 10)"` may cause the workflow to fail if the API can't consistently respond within 10 ms. Comparing the failed run with an earlier successful run can help identify regressions, increased response times, or higher error rates introduced by recent changes.