Use a dataset to simulate virtual users

When you configure a performance test, each virtual user (VU) runs the selected requests in a repeating loop. By default, every virtual user sends requests with the same data. You can use a dataset to give each virtual user its own row of data, so each one sends requests with unique values such as logins, tokens, or payloads.

Unlike a data file, which is a static CSV or JSON file uploaded per run, a dataset is a data source shared across your collections, mocks, and runs. You define the data once and shape it with views, so the same dataset can power your collection runs, mock servers, and performance tests without duplication. Datasets can be backed by local files or live external databases.

A dataset has no file size limit, so you can drive a test from a larger set of rows. A larger dataset doesn’t slow down tests because data is fetched during preparation of the performance run and doesn’t fall into the critical path of sending requests. This is why no latency is added to your requests.

You can select an existing dataset or create one from a data file without leaving the performance test configuration.

Run a performance test with a dataset

You can use a dataset with the App, Postman CLI, and Cloud run methods. The App run method is available in the Postman desktop app only and supports both datasets and data files. The Postman CLI runs a test from the command line, such as in CI/CD or on another machine, and supports both datasets and data files. Cloud runs support datasets only. Learn more about run methods.

For Postman CLI runs, see Configure and validate performance tests using the Postman CLI.

To run a performance test with a dataset from the App or Cloud, do the following:

1. Click Items in the sidebar, then click Collections and select the collection you want to run.

2. Reference the dataset fields in your requests. See Access data in scripts.

3. Select the collection again and click Run in the upper right.

4. Select Performance, then select App or Cloud.

5. Under Iteration data, do one of the following, depending on your run method:

   • For App runs, click the Datasets tab.
   • For Cloud runs, search for a dataset directly. Cloud runs support datasets only, so there’s no tab to select.
   To create a new dataset from a data file without leaving the performance test configuration, click Add file at the end of the list. See Create a dataset from a data file.

6. Select a dataset and a view. The view controls which rows and columns are available to virtual users during the test.

7. Under Iteration Strategies, select how rows are mapped to virtual users. Learn more about iteration strategies.

8. Click Start run to start the performance test.

Create a dataset from a data file

If you don’t have a dataset yet, you can create one when configuring a performance test by uploading a CSV or JSON file. Postman adds the data file as a data source and view, and selects it as your iteration data. The dataset is added to your workspace so it’s available for future performance test configurations.

To create a dataset from a data file when configuring a performance test, do the following:

1. Click Items in the sidebar, then click Collections and select the collection you want to run.

2. Select the collection again and click Run in the upper right.

3. Select Performance, then select App, Postman CLI, or Cloud.

4. Under Iteration data, click Add file at the end of the list. If you’re running the performance test in the app, you need to select the Datasets tab before you can add the file.

5. Select a CSV or JSON file from your local machine. You can drag and drop the file or click browse to select it manually.

6. Confirm the file name. To use a different file, click to replace it, or click to remove it.

7. (Optional) To save the file to a specific or new dataset, expand More options and do the following:

   • In the Dataset dropdown, select an existing dataset, or select New dataset… to create one. If you select New dataset…, enter a name for the dataset.
   • In the View name field, review or update the view name. This is pre-filled from the file name.
   • (Optional) In the Description field, enter a description for the view.

8. Click Save.

After saving, the dataset appears in the sidebar and Iteration data is set to the new dataset and view. The Data tab opens, showing a table preview of the data. The first row of the preview, labeled var, shows the variable name for each field. For example, {{name}}, {{age}}, {{city}}. Use these in your requests to reference values for each iteration. The Query pane below the preview shows the SQL for the view, which you can edit and save or save as a new view.

Iteration strategies

Iteration strategies control how the rows from your selected view are assigned to virtual users during the run. They reuse the rows you have to cover every virtual user and don’t generate new rows, so rows repeat when there are more virtual users than rows. The strategies differ in whether a virtual user keeps the same row for the whole test or takes a new one each time it runs the requests. For example, if your view returns 500 rows and you run 1,000 virtual users:

• Round-robin (default) — Rows are handed out in the order requests are made, not per virtual user: the first request uses row 1, the next uses row 2, and after the last row the rotation wraps back to row 1 and keeps cycling. Because the rotation is shared, a single virtual user doesn’t step through the rows in order. It takes whatever row is next each time it sends a request. With 500 rows, requests cycle through rows 1 to 500 and repeat for the rest of the test, giving even coverage across all rows.

• Fixed — Each virtual user is pinned to a single row and uses it for the entire test, so its data never changes. VU N uses row N, wrapping past the last row. With 500 rows, virtual users 501 to 1,000 reuse rows 1 to 500, so each row serves two virtual users. Use this when a virtual user must represent one identity throughout the test, such as load-testing real auth or per-user flows.

• Random — Each time a virtual user runs the requests, it takes a uniformly random row, so its data changes on each loop but without any order. With 500 rows, some rows might be used many times and others might never be used, so there’s no coverage or uniqueness guarantee. Use this to simulate unpredictable, mixed traffic.

Access data in scripts

During the performance test, each virtual user’s assigned row is available in pre-request and post-response scripts using pm.iterationData. The keys you pass to pm.iterationData.get() correspond to the fields exposed by the view you selected. For example, if your view includes a token field, each virtual user can authenticate with a unique token:

const token = pm.iterationData.get('token');
pm.request.headers.upsert({
    key: 'Authorization',
    value: `Bearer ${token}`
});

Learn more about using iteration data variables in scripts.