Use a dataset with a monitor

You can use a Postman dataset and its views as iteration data for a monitor run. Every row returned by the selected view becomes one collection iteration, available through pm.iterationData. Datasets are shared across workflows, so the same data can power collection runs, code mocks, and monitors without duplication. Because a monitor resolves the current dataset view each time it runs, scheduled tests can use the latest data without re-uploading files. You can select an existing dataset or create one from a data file without leaving the monitor configuration. To access local data files or external data sources with a monitor, you must use a Private API Monitoring runner.

Data source support

Where a monitor runs determines which of a dataset’s data sources it can use:

• Monitors that run in the Postman Cloud — Can use datasets with Postman Cloud Store data sources only. Postman’s cloud infrastructure can’t reach local files or databases inside your network.
• Monitors that use a Private API Monitoring runner — Can use all data source types, including local files, MySQL, Postgres, SQL Server, and custom JDBC data sources. The runner reads each data source from the machine it runs on, so that machine needs access to the underlying file or database. A custom JDBC data source also needs Java 8 or newer and a folder of driver files on that machine. Learn more about using datasets with a runner.

If a monitor can’t reach a dataset’s data sources, the run fails without sending any requests and the monitor is marked unhealthy. The Errors tab of the run shows the reason, such as DatasetExecutionError: Monitors only support datasources uploaded to Postman Cloud.

Prepare your collection

Add variables to the requests in your collection. Variable names should match the field names exposed by the view you select. For example, if your view includes a userId field, reference it as {{userId}} in a request URL. Create a dataset with at least one view that returns the data you want to use.

During a monitor run, the view’s field values are also available in pre-request and post-response scripts through pm.iterationData. Learn more about using iteration data variables in scripts.

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

You can also use the pm.datasets function to run saved views or run read-only SQL queries in scripts while a monitor is running. Learn more at Manage and use datasets in scripts.

Use a dataset with a monitor

When you configure a monitor, you can select a dataset view to provide iteration data for the monitor run. You must use Private API Monitoring runners to access local data files or external data sources.

To select a dataset when configuring a monitor, do the following:

1. Create or edit a monitor.

2. Under Iteration data, click the dropdown list and select a dataset view.

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

   A preview of the dataset view appears in the right pane. The var row shows the variable name for each field, such as {{userId}}, so you can copy the syntax to reference in your requests. From here, you can do the following:

   • Edit the view and click Run to preview the results.
   • Click Save to save your changes to the view.
   • Click Save as new view to save the changes as a separate view. The monitor automatically switches to the new view.
   • Click Reset to discard changes and return to the original view.

3. Select an Iteration strategy for the run. Learn more about iteration strategies.

4. Enter the number of iterations. Not available for the Default iteration strategy.

5. Complete the remaining monitor configuration and save the monitor.

Create a dataset from a data file

If you don’t have a dataset yet, you can create one when configuring a monitor 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 monitor configurations.

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

1. Click the Iteration data dropdown list.

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.

Iteration strategies

An iteration strategy determines what happens when the number of configured iterations differs from the number of rows returned by the selected view.

• Default — The monitor runs one iteration for each row returned by the view.
• Round robin — If iterations exceed the number of rows, the monitor starts again from the first row for the remaining iterations.
• Repeat last — If iterations exceed the number of rows, the monitor reuses the last row for the remaining iterations.
• Stop at end — The monitor stops when it runs out of rows, regardless of the configured number of iterations.