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, you can run performance tests for Postman Collections locally, as part of your CI/CD pipeline, or on Postman’s managed cloud infrastructure. This enables your team to automatically detect performance regressions during development and deployment workflows.

The postman performance run command 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.

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 for performance testing, or reuse an existing collection and modify it for load testing scenarios.

When preparing your collection, choose requests 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 to validate response status codes, response times, and other performance-related behaviors during load testing.

You can also use Agent Mode 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:

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 Postman CLI.
6. Configure the load profile, virtual user count, and test duration.
7. Optionally, select a dataset and view to use as test data.
8. 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.
9. Optionally, use the Setup and Teardown dropdowns to attach collections that run once before and/or after the test. Learn more about running setup and teardown collections.
10. Under Install Postman CLI, click Copy to clipboard to copy the Postman CLI installation command.
11. Install the Postman CLI on your local machine.
12. 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.
13. Click Insert Key.
14. Click Copy to clipboard to copy the login and performance commands.
15. 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:

$
postman login --with-api-key <postman-api-key>
$
$
postman performance run <collection-id> --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.

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.

1
name: Performance Tests
2
3
on:
4
  push:
5
    branches: [main]
6
  pull_request:
7
    branches: [main]
8
9
jobs:
10
  performance:
11
    name: Run Performance Test
12
    runs-on: ubuntu-latest
13
14
    steps:
15
      - name: Checkout
16
        uses: actions/checkout@v4
17
18
      - name: Install Postman CLI
19
        run: |
20
          curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
21
22
      - name: Login to Postman CLI
23
        run: postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
24
25
      - name: Run Postman performance test
26
        run: |
27
          postman performance run "${{ vars.COLLECTION_ID }}" \
28
            --vu-count 20 \
29
            --duration 10 \
30
            --load-profile spike \
31
            --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.

Run setup and teardown collections

Setup and teardown collections let you run preparation and cleanup steps once for a performance test, so CI/CD workflows don’t have to manage those steps with external scripts or build them into the workload collection. The setup collection runs once before the test starts, and the teardown collection runs once after the test ends, on every outcome. Setup and teardown collections require the --runner postman-cloud option. Learn more about how setup and teardown run.

Add the --setup-collection and --teardown-collection options to the postman performance run command. Specify each collection by its ID — collection names aren’t supported. You can use either option on its own, and you can use the same collection for both.

$
postman performance run <workload-collection-id> \
>
  --runner postman-cloud \
>
  --setup-collection <setup-collection-id> \
>
  --teardown-collection <teardown-collection-id> \
>
  --environment <environment-id>

Setup, the performance test, and teardown share state through environment variables, so specify an environment with --environment. Variables the setup collection writes are passed to the virtual users and to the teardown collection. Learn more about passing state between phases and the --setup-collection and --teardown-collection options.

Run a performance test on Postman Cloud

By default, postman performance run generates load from the machine that invokes it, whether that’s your local machine or a CI/CD runner. Add the --runner postman-cloud option to originate the load from Postman’s managed cloud infrastructure instead, with no change to the collection, the test configuration, or how results are reported.

$
postman performance run <collection-id> --runner postman-cloud --vu-count 500 --duration 30

Use a cloud runner to generate load beyond what your local machine or CI/CD runner can produce, without moving the test out of your existing pipeline. The --runner option is repeatable, so a single run can originate load from more than one runner. Learn more about the --runner option.

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.

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.