Use a dataset with a collection run

When you run a collection, you can use a dataset as iteration data. Each row returned by the selected view becomes one iteration, so the same requests run with different inputs. Unlike a data file, a dataset is reusable and queryable, and it isn’t subject to file size limits. You can select an existing dataset or create one from a data file without leaving the Collection Runner.

Run a collection with a dataset

Select a dataset and view to use as iteration data. The view controls which rows and columns are available during the run.

To run a collection with a dataset, 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 Use iteration data in requests and Use iteration data in scripts.

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

4. Select Functional, then select Local.

5. Click the Iteration data dropdown list and select the Datasets tab.

6. Select the dataset you want to use, then select a view with the data you want to run against.

   To create a new dataset from a data file without leaving the Collection Runner, click Add file at the end of the list. See Create a dataset from a data file.

7. (Optional) Click the Data tab in the left pane to preview the view you selected.

8. (Optional) Control how many iterations run.

9. Click Start run.

The collection run summary shows the data used for each iteration.

Create a dataset from a data file

If you don’t have a dataset yet, you can create one from the Collection Runner 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 runs.

To create a dataset from a file in the Collection Runner, do the following:

1. Click the Iteration data dropdown list and select the Datasets tab.

2. Click Add file at the end of the list and select a CSV or JSON file from your local machine. You can drag and drop the file or click browse to select it manually.

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

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

   • In the Dataset dropdown list, 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.

5. 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.

Control how many iterations run

By default, Postman sets the number of iterations to the number of rows returned by the selected view, running one iteration for each row. You can change how many iterations run and how Postman assigns data when there are more iterations than rows:

• Iterations — Enter the number of times to run the collection. If you enter fewer iterations than the number of rows in the view, Postman uses the first rows in the view, one for each iteration.

• Iteration strategy — Select how the extra iterations get their data when the view’s rows run out:

  • Round robin — Continue from the first row for the remaining iterations.
  • Repeat last — Continue using the last row for the remaining iterations.
  • Stop at end — Stop the run when the rows run out.

Use iteration data in requests

Dataset fields are automatically exposed as variables during the run. You can reference them using the {{variable}} syntax. For example, if your dataset has a userId field, reference it in your request URL as {{userId}}. Learn more about using variables.

GET /user?userId={{userId}}&email={{email}}&name={{name}}

Use iteration data in scripts

You can access the values from the current iteration in pre-request and post-response scripts using pm.iterationData. Learn more about using iteration data variables in scripts.

console.log(pm.iterationData.get("email"));

For more advanced usage, such as querying the dataset beyond the current iteration or referencing datasets, sources, and views by ID, see Query datasets in scripts.